@emara/ui 1.1.0

package/components/ui/page-header.tsx

@@ -0,0 +1,315 @@
+"use client";
+
+import { createContext, forwardRef, useContext, useMemo } from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { RiArrowLeftSLine } from "@remixicon/react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+import { Button } from "./button";
+
+// Per docs/emara-ui-phase-5-components.md §4.
+
+type PageHeaderVariant = "default" | "compact" | "splash";
+type PageHeaderSize = "sm" | "md" | "lg";
+
+interface PageHeaderContextValue {
+  variant: PageHeaderVariant;
+  size: PageHeaderSize;
+}
+
+const PageHeaderContext = createContext<PageHeaderContextValue | null>(null);
+
+function usePageHeader(): PageHeaderContextValue {
+  const ctx = useContext(PageHeaderContext);
+  if (!ctx) throw new Error("PageHeader subcomponents must be used inside <PageHeader>");
+  return ctx;
+}
+
+// ---- Root ------------------------------------------------------------------
+
+const rootVariants = cva("w-full", {
+  variants: {
+    variant: {
+      default: "",
+      compact: "",
+      splash: "",
+    },
+    size: {
+      sm: "",
+      md: "",
+      lg: "",
+    },
+    divider: { true: "border-b border-border", false: "" },
+    sticky: { true: "sticky top-0 z-sticky bg-background/95 backdrop-blur", false: "" },
+  },
+  compoundVariants: [
+    { variant: "default", size: "sm", class: "py-3 space-y-2" },
+    { variant: "default", size: "md", class: "py-4 space-y-3" },
+    { variant: "default", size: "lg", class: "py-6 space-y-4" },
+    { variant: "compact", size: "sm", class: "py-2 space-y-1" },
+    { variant: "compact", size: "md", class: "py-2.5 space-y-1" },
+    { variant: "compact", size: "lg", class: "py-3 space-y-2" },
+    { variant: "splash", size: "sm", class: "py-6 space-y-3" },
+    { variant: "splash", size: "md", class: "py-10 space-y-4" },
+    { variant: "splash", size: "lg", class: "py-14 space-y-6" },
+  ],
+  defaultVariants: { variant: "default", size: "md", divider: false, sticky: false },
+});
+
+type RootVariants = VariantProps<typeof rootVariants>;
+
+type PageHeaderProps = Omit<React.HTMLAttributes<HTMLElement>, "title"> &
+  RootVariants & {
+    asChild?: boolean;
+    /** Convenience: rendered as PageHeaderTitle (with `as="h1"`). */
+    title?: React.ReactNode;
+    /** Convenience: rendered as PageHeaderDescription. */
+    description?: React.ReactNode;
+    /** Convenience: slot for breadcrumb (`<Breadcrumbs />` or primitives). */
+    breadcrumb?: React.ReactNode;
+    /** Convenience: rendered into PageHeaderActions. */
+    actions?: React.ReactNode;
+    /** Convenience: renders a default back button linking here. */
+    backHref?: string;
+    /** Localized aria-label for the auto-injected BackButton. Default "Back". */
+    backLabel?: string;
+    /** Convenience: rendered as PageHeaderTabs. */
+    tabs?: React.ReactNode;
+  };
+
+const PageHeader = forwardRef<HTMLElement, PageHeaderProps>(function PageHeader(
+  {
+    className,
+    variant = "default",
+    size = "md",
+    divider = false,
+    sticky = false,
+    asChild = false,
+    title,
+    description,
+    breadcrumb,
+    actions,
+    backHref,
+    backLabel = "Back",
+    tabs,
+    children,
+    ...props
+  },
+  ref,
+) {
+  const Comp = asChild ? Slot : "header";
+  const resolvedVariant: PageHeaderVariant = variant ?? "default";
+  const resolvedSize: PageHeaderSize = size ?? "md";
+  const ctx = useMemo(
+    () => ({ variant: resolvedVariant, size: resolvedSize }),
+    [resolvedVariant, resolvedSize],
+  );
+
+  const usingConvenience =
+    title !== undefined ||
+    description !== undefined ||
+    breadcrumb !== undefined ||
+    actions !== undefined ||
+    backHref !== undefined ||
+    tabs !== undefined;
+
+  return (
+    <PageHeaderContext.Provider value={ctx}>
+      <Comp
+        ref={ref}
+        className={cn(rootVariants({ variant, size, divider, sticky }), className)}
+        {...props}
+      >
+        {usingConvenience ? (
+          <>
+            {breadcrumb ? <PageHeaderBreadcrumb>{breadcrumb}</PageHeaderBreadcrumb> : null}
+            <PageHeaderTop>
+              {backHref ? <PageHeaderBackButton href={backHref} label={backLabel} /> : null}
+              {title ? <PageHeaderTitle>{title}</PageHeaderTitle> : null}
+              <span className="flex-1" />
+              {actions ? <PageHeaderActions>{actions}</PageHeaderActions> : null}
+            </PageHeaderTop>
+            {description ? <PageHeaderDescription>{description}</PageHeaderDescription> : null}
+            {tabs ? <PageHeaderTabs>{tabs}</PageHeaderTabs> : null}
+          </>
+        ) : (
+          children
+        )}
+      </Comp>
+    </PageHeaderContext.Provider>
+  );
+});
+PageHeader.displayName = "PageHeader";
+
+// ---- Breadcrumb slot -------------------------------------------------------
+
+const PageHeaderBreadcrumb = forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  function PageHeaderBreadcrumb({ className, ...props }, ref) {
+    return <div ref={ref} className={cn("text-sm", className)} {...props} />;
+  },
+);
+PageHeaderBreadcrumb.displayName = "PageHeaderBreadcrumb";
+
+// ---- Top (back + title + actions row) --------------------------------------
+
+const PageHeaderTop = forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  function PageHeaderTop({ className, ...props }, ref) {
+    return (
+      <div ref={ref} className={cn("flex flex-wrap items-center gap-3", className)} {...props} />
+    );
+  },
+);
+PageHeaderTop.displayName = "PageHeaderTop";
+
+// ---- BackButton ------------------------------------------------------------
+
+type PageHeaderBackButtonProps = Omit<React.ComponentProps<typeof Button>, "size"> & {
+  /** Required: where to go back to. */
+  href: string;
+  /** aria-label. Default "Back". */
+  label?: string;
+};
+
+const PageHeaderBackButton = forwardRef<HTMLButtonElement, PageHeaderBackButtonProps>(
+  function PageHeaderBackButton({ className, href, label = "Back", children, ...props }, ref) {
+    return (
+      <Button
+        ref={ref}
+        asChild
+        variant="ghost"
+        size="icon-sm"
+        aria-label={label}
+        className={cn(className)}
+        {...props}
+      >
+        <a href={href}>
+          <RiArrowLeftSLine className="rtl-mirror" />
+          {children ? <span className="ms-1">{children}</span> : null}
+        </a>
+      </Button>
+    );
+  },
+);
+PageHeaderBackButton.displayName = "PageHeaderBackButton";
+
+// ---- Title -----------------------------------------------------------------
+
+const titleVariants = cva("font-semibold tracking-tight text-foreground", {
+  variants: {
+    variant: {
+      default: "",
+      compact: "",
+      splash: "",
+    },
+    size: {
+      sm: "",
+      md: "",
+      lg: "",
+    },
+  },
+  compoundVariants: [
+    { variant: "default", size: "sm", class: "text-lg" },
+    { variant: "default", size: "md", class: "text-2xl" },
+    { variant: "default", size: "lg", class: "text-3xl" },
+    { variant: "compact", size: "sm", class: "text-base" },
+    { variant: "compact", size: "md", class: "text-lg" },
+    { variant: "compact", size: "lg", class: "text-xl" },
+    { variant: "splash", size: "sm", class: "text-2xl" },
+    { variant: "splash", size: "md", class: "text-4xl" },
+    { variant: "splash", size: "lg", class: "text-5xl" },
+  ],
+  defaultVariants: { variant: "default", size: "md" },
+});
+
+type PageHeaderTitleProps = React.HTMLAttributes<HTMLHeadingElement> & {
+  as?: "h1" | "h2";
+};
+
+const PageHeaderTitle = forwardRef<HTMLHeadingElement, PageHeaderTitleProps>(
+  function PageHeaderTitle({ as: Heading = "h1", className, ...props }, ref) {
+    const { variant, size } = usePageHeader();
+    return (
+      <Heading ref={ref} className={cn(titleVariants({ variant, size }), className)} {...props} />
+    );
+  },
+);
+PageHeaderTitle.displayName = "PageHeaderTitle";
+
+// ---- Badge slot (next to title) -------------------------------------------
+
+const PageHeaderBadge = forwardRef<HTMLSpanElement, React.HTMLAttributes<HTMLSpanElement>>(
+  function PageHeaderBadge({ className, ...props }, ref) {
+    return <span ref={ref} className={cn("inline-flex items-center", className)} {...props} />;
+  },
+);
+PageHeaderBadge.displayName = "PageHeaderBadge";
+
+// ---- Actions ---------------------------------------------------------------
+
+const PageHeaderActions = forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  function PageHeaderActions({ className, ...props }, ref) {
+    return (
+      <div ref={ref} className={cn("flex flex-wrap items-center gap-2", className)} {...props} />
+    );
+  },
+);
+PageHeaderActions.displayName = "PageHeaderActions";
+
+// ---- Description -----------------------------------------------------------
+
+const descriptionVariants = cva("text-muted-foreground", {
+  variants: {
+    size: {
+      sm: "text-xs",
+      md: "text-sm",
+      lg: "text-base",
+    },
+  },
+  defaultVariants: { size: "md" },
+});
+
+const PageHeaderDescription = forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(function PageHeaderDescription({ className, ...props }, ref) {
+  const { size } = usePageHeader();
+  return (
+    <p
+      ref={ref}
+      className={cn(descriptionVariants({ size }), "max-w-prose", className)}
+      {...props}
+    />
+  );
+});
+PageHeaderDescription.displayName = "PageHeaderDescription";
+
+// ---- Tabs slot (no padding underneath) ------------------------------------
+
+const PageHeaderTabs = forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  function PageHeaderTabs({ className, ...props }, ref) {
+    return (
+      <div
+        ref={ref}
+        // The slot sits flush with the bottom edge so a `divider` line passes
+        // under the active tab indicator.
+        className={cn("-mb-px", className)}
+        {...props}
+      />
+    );
+  },
+);
+PageHeaderTabs.displayName = "PageHeaderTabs";
+
+export {
+  PageHeader,
+  PageHeaderBreadcrumb,
+  PageHeaderTop,
+  PageHeaderBackButton,
+  PageHeaderTitle,
+  PageHeaderBadge,
+  PageHeaderActions,
+  PageHeaderDescription,
+  PageHeaderTabs,
+};
+export type { PageHeaderProps, PageHeaderTitleProps, PageHeaderBackButtonProps };

package/components/ui/pagination.stories.tsx

@@ -0,0 +1,136 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+
+import {
+  DataPagination,
+  Pagination,
+  PaginationContent,
+  PaginationEllipsis,
+  PaginationItem,
+  PaginationLink,
+  PaginationNext,
+  PaginationPrevious,
+} from "./pagination";
+
+const meta: Meta<typeof DataPagination> = {
+  title: "Data/Pagination",
+  component: DataPagination,
+  parameters: { layout: "padded" },
+  argTypes: {
+    size: { control: "select", options: ["sm", "md", "lg"] },
+    siblingCount: { control: "number" },
+    boundaryCount: { control: "number" },
+    showInfo: { control: "boolean" },
+    showPageSize: { control: "boolean" },
+    showFirstLast: { control: "boolean" },
+    disabled: { control: "boolean" },
+    loading: { control: "boolean" },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof DataPagination>;
+
+function DataDemo(props: Partial<React.ComponentProps<typeof DataPagination>>) {
+  const [page, setPage] = useState(props.page ?? 3);
+  const [size, setSize] = useState(props.pageSize ?? 25);
+  return (
+    <DataPagination
+      page={page}
+      pageCount={props.pageCount ?? 10}
+      onPageChange={setPage}
+      pageSize={size}
+      pageSizeOptions={props.pageSizeOptions ?? [10, 25, 50, 100]}
+      onPageSizeChange={setSize}
+      totalItems={props.totalItems ?? 247}
+      size={props.size ?? "md"}
+      siblingCount={props.siblingCount ?? 1}
+      boundaryCount={props.boundaryCount ?? 1}
+      {...(props.showInfo !== undefined ? { showInfo: props.showInfo } : {})}
+      {...(props.showPageSize !== undefined ? { showPageSize: props.showPageSize } : {})}
+      {...(props.showFirstLast !== undefined ? { showFirstLast: props.showFirstLast } : {})}
+      {...(props.disabled !== undefined ? { disabled: props.disabled } : {})}
+      {...(props.loading !== undefined ? { loading: props.loading } : {})}
+    />
+  );
+}
+
+export const Default: Story = {
+  render: () => <DataDemo />,
+};
+
+export const WithFirstLast: Story = {
+  render: () => <DataDemo showFirstLast />,
+};
+
+export const NoPageSize: Story = {
+  render: () => (
+    <DataPagination
+      page={3}
+      pageCount={10}
+      onPageChange={() => {}}
+      totalItems={247}
+      pageSize={25}
+    />
+  ),
+};
+
+export const LargePageCount: Story = {
+  render: () => <DataDemo pageCount={50} page={20} totalItems={1200} />,
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="space-y-4">
+      <DataDemo size="sm" />
+      <DataDemo size="md" />
+      <DataDemo size="lg" />
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => <DataDemo disabled />,
+};
+
+/**
+ * Loading state — all interactive controls become non-interactive while
+ * the underlying data is fetching. Mirrors `disabled` visually but
+ * communicates "fetching" rather than "unavailable".
+ */
+export const Loading: Story = {
+  render: () => <DataDemo loading />,
+};
+
+/** Pagination primitives — composed manually. */
+export const Primitives: Story = {
+  render: () => (
+    <Pagination>
+      <span />
+      <PaginationContent>
+        <PaginationItem>
+          <PaginationPrevious />
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationLink>1</PaginationLink>
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationLink isActive>2</PaginationLink>
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationLink>3</PaginationLink>
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationEllipsis />
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationLink>10</PaginationLink>
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationNext />
+        </PaginationItem>
+      </PaginationContent>
+      <span />
+    </Pagination>
+  ),
+};