@emara/ui 1.1.0

package/components/ui/pagination.tsx

@@ -0,0 +1,427 @@
+"use client";
+
+import { forwardRef, useMemo } from "react";
+import {
+  RiArrowLeftDoubleLine,
+  RiArrowLeftSLine,
+  RiArrowRightDoubleLine,
+  RiArrowRightSLine,
+  RiMoreLine,
+} from "@remixicon/react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+import { buttonVariants } from "./button";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "./select";
+
+// Per docs/emara-ui-phase-4-components.md §2.
+
+// ===========================================================================
+// 2.1 Primitives
+// ===========================================================================
+
+const Pagination = forwardRef<HTMLElement, React.HTMLAttributes<HTMLElement>>(function Pagination(
+  { className, ...props },
+  ref,
+) {
+  return (
+    <nav
+      ref={ref}
+      role="navigation"
+      aria-label="Pagination"
+      className={cn("flex w-full items-center justify-between gap-3", className)}
+      {...props}
+    />
+  );
+});
+Pagination.displayName = "Pagination";
+
+const PaginationContent = forwardRef<HTMLUListElement, React.HTMLAttributes<HTMLUListElement>>(
+  function PaginationContent({ className, ...props }, ref) {
+    return (
+      <ul ref={ref} className={cn("flex flex-row items-center gap-1", className)} {...props} />
+    );
+  },
+);
+PaginationContent.displayName = "PaginationContent";
+
+const PaginationItem = forwardRef<HTMLLIElement, React.LiHTMLAttributes<HTMLLIElement>>(
+  function PaginationItem({ className, ...props }, ref) {
+    return <li ref={ref} className={cn("", className)} {...props} />;
+  },
+);
+PaginationItem.displayName = "PaginationItem";
+
+const paginationLinkVariants = cva(
+  "inline-flex items-center justify-center select-none transition-colors gap-1 cursor-pointer disabled:pointer-events-none disabled:opacity-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+  {
+    variants: {
+      size: {
+        sm: "h-8 min-w-8 text-xs rounded-md px-2.5",
+        md: "h-9 min-w-9 text-sm rounded-md px-3",
+        lg: "h-10 min-w-10 text-base rounded-md px-3.5",
+      },
+      active: {
+        true: "bg-primary text-primary-foreground hover:bg-primary/90",
+        false:
+          "text-foreground hover:bg-accent hover:text-accent-foreground border border-input bg-background",
+      },
+    },
+    defaultVariants: { size: "md", active: false },
+  },
+);
+
+type PaginationLinkProps = React.ButtonHTMLAttributes<HTMLButtonElement> &
+  VariantProps<typeof paginationLinkVariants> & {
+    isActive?: boolean;
+  };
+
+const PaginationLink = forwardRef<HTMLButtonElement, PaginationLinkProps>(function PaginationLink(
+  { className, size, active, isActive, type = "button", ...props },
+  ref,
+) {
+  const resolvedActive = active ?? isActive ?? false;
+  return (
+    <button
+      ref={ref}
+      type={type}
+      aria-current={resolvedActive ? "page" : undefined}
+      className={cn(paginationLinkVariants({ size, active: resolvedActive }), className)}
+      {...props}
+    />
+  );
+});
+PaginationLink.displayName = "PaginationLink";
+
+// Prev / Next ----------------------------------------------------------------
+
+type PaginationDirectionalProps = React.ButtonHTMLAttributes<HTMLButtonElement> &
+  VariantProps<typeof paginationLinkVariants> & {
+    label?: string;
+  };
+
+const PaginationPrevious = forwardRef<HTMLButtonElement, PaginationDirectionalProps>(
+  function PaginationPrevious(
+    { className, size, label = "Go to previous page", type = "button", ...props },
+    ref,
+  ) {
+    // Use `buttonVariants` shape for outline look; primary visual is the link variant.
+    void buttonVariants;
+    return (
+      <button
+        ref={ref}
+        type={type}
+        aria-label={label}
+        className={cn(
+          paginationLinkVariants({ size, active: false }),
+          "[&_svg]:size-4 [&_svg]:shrink-0",
+          className,
+        )}
+        {...props}
+      >
+        <RiArrowLeftSLine className="rtl-mirror" />
+      </button>
+    );
+  },
+);
+PaginationPrevious.displayName = "PaginationPrevious";
+
+const PaginationNext = forwardRef<HTMLButtonElement, PaginationDirectionalProps>(
+  function PaginationNext(
+    { className, size, label = "Go to next page", type = "button", ...props },
+    ref,
+  ) {
+    return (
+      <button
+        ref={ref}
+        type={type}
+        aria-label={label}
+        className={cn(
+          paginationLinkVariants({ size, active: false }),
+          "[&_svg]:size-4 [&_svg]:shrink-0",
+          className,
+        )}
+        {...props}
+      >
+        <RiArrowRightSLine className="rtl-mirror" />
+      </button>
+    );
+  },
+);
+PaginationNext.displayName = "PaginationNext";
+
+const PaginationFirst = forwardRef<HTMLButtonElement, PaginationDirectionalProps>(
+  function PaginationFirst(
+    { className, size, label = "Go to first page", type = "button", ...props },
+    ref,
+  ) {
+    return (
+      <button
+        ref={ref}
+        type={type}
+        aria-label={label}
+        className={cn(
+          paginationLinkVariants({ size, active: false }),
+          "[&_svg]:size-4 [&_svg]:shrink-0",
+          className,
+        )}
+        {...props}
+      >
+        <RiArrowLeftDoubleLine className="rtl-mirror" />
+      </button>
+    );
+  },
+);
+PaginationFirst.displayName = "PaginationFirst";
+
+const PaginationLast = forwardRef<HTMLButtonElement, PaginationDirectionalProps>(
+  function PaginationLast(
+    { className, size, label = "Go to last page", type = "button", ...props },
+    ref,
+  ) {
+    return (
+      <button
+        ref={ref}
+        type={type}
+        aria-label={label}
+        className={cn(
+          paginationLinkVariants({ size, active: false }),
+          "[&_svg]:size-4 [&_svg]:shrink-0",
+          className,
+        )}
+        {...props}
+      >
+        <RiArrowRightDoubleLine className="rtl-mirror" />
+      </button>
+    );
+  },
+);
+PaginationLast.displayName = "PaginationLast";
+
+const PaginationEllipsis = forwardRef<HTMLSpanElement, React.HTMLAttributes<HTMLSpanElement>>(
+  function PaginationEllipsis({ className, ...props }, ref) {
+    return (
+      <span
+        ref={ref}
+        aria-hidden="true"
+        className={cn(
+          "text-muted-foreground inline-flex h-9 min-w-9 items-center justify-center",
+          "[&_svg]:size-4 [&_svg]:shrink-0",
+          className,
+        )}
+        {...props}
+      >
+        <RiMoreLine />
+        <span className="sr-only">More pages</span>
+      </span>
+    );
+  },
+);
+PaginationEllipsis.displayName = "PaginationEllipsis";
+
+// ===========================================================================
+// 2.2 DataPagination
+// ===========================================================================
+
+interface DataPaginationProps {
+  page: number;
+  pageCount: number;
+  onPageChange: (page: number) => void;
+  pageSize?: number;
+  pageSizeOptions?: number[];
+  onPageSizeChange?: (size: number) => void;
+  totalItems?: number;
+  siblingCount?: number;
+  boundaryCount?: number;
+  showInfo?: boolean;
+  showPageSize?: boolean;
+  showFirstLast?: boolean;
+  size?: "sm" | "md" | "lg";
+  disabled?: boolean;
+  loading?: boolean;
+  className?: string;
+}
+
+/** Builds the list of page tokens to render. */
+function buildPageList(
+  page: number,
+  pageCount: number,
+  siblingCount: number,
+  boundaryCount: number,
+): Array<number | "ellipsis-start" | "ellipsis-end"> {
+  if (pageCount <= 0) return [];
+  const totalNumbers = siblingCount * 2 + boundaryCount * 2 + 3;
+  if (pageCount <= totalNumbers) {
+    return Array.from({ length: pageCount }, (_, i) => i + 1);
+  }
+  const startPages = Array.from({ length: boundaryCount }, (_, i) => i + 1);
+  const endPages = Array.from(
+    { length: boundaryCount },
+    (_, i) => pageCount - boundaryCount + i + 1,
+  );
+
+  const siblingsStart = Math.max(
+    Math.min(page - siblingCount, pageCount - boundaryCount - siblingCount * 2 - 1),
+    boundaryCount + 2,
+  );
+  const siblingsEnd = Math.min(
+    Math.max(page + siblingCount, boundaryCount + siblingCount * 2 + 2),
+    pageCount - boundaryCount - 1,
+  );
+
+  const middle = Array.from(
+    { length: Math.max(siblingsEnd - siblingsStart + 1, 0) },
+    (_, i) => siblingsStart + i,
+  );
+
+  const result: Array<number | "ellipsis-start" | "ellipsis-end"> = [...startPages];
+  if (siblingsStart > boundaryCount + 2) result.push("ellipsis-start");
+  else if (boundaryCount + 1 < pageCount - boundaryCount) result.push(boundaryCount + 1);
+  result.push(...middle);
+  if (siblingsEnd < pageCount - boundaryCount - 1) result.push("ellipsis-end");
+  else if (pageCount - boundaryCount > boundaryCount) result.push(pageCount - boundaryCount);
+  result.push(...endPages);
+  return Array.from(new Set(result));
+}
+
+const DataPagination = forwardRef<HTMLElement, DataPaginationProps>(function DataPagination(
+  {
+    page,
+    pageCount,
+    onPageChange,
+    pageSize,
+    pageSizeOptions,
+    onPageSizeChange,
+    totalItems,
+    siblingCount = 1,
+    boundaryCount = 1,
+    showInfo = true,
+    showPageSize,
+    showFirstLast = false,
+    size = "md",
+    disabled = false,
+    loading = false,
+    className,
+  },
+  ref,
+) {
+  const pages = useMemo(
+    () => buildPageList(page, pageCount, siblingCount, boundaryCount),
+    [page, pageCount, siblingCount, boundaryCount],
+  );
+
+  const isDisabled = disabled || loading;
+  const onFirst = () => onPageChange(1);
+  const onPrev = () => onPageChange(Math.max(1, page - 1));
+  const onNext = () => onPageChange(Math.min(pageCount, page + 1));
+  const onLast = () => onPageChange(pageCount);
+
+  const start = pageSize && totalItems ? Math.min((page - 1) * pageSize + 1, totalItems) : null;
+  const end = pageSize && totalItems ? Math.min(page * pageSize, totalItems) : null;
+
+  const showSizeSelector =
+    (showPageSize ?? Boolean(pageSizeOptions && pageSizeOptions.length > 0)) &&
+    pageSizeOptions &&
+    pageSize !== undefined &&
+    onPageSizeChange;
+
+  return (
+    <Pagination ref={ref} className={cn("flex-wrap gap-3", className)}>
+      {showInfo && start !== null && end !== null && totalItems !== undefined ? (
+        // Announce range changes to screen readers without re-announcing the
+        // whole pagination — `aria-live="polite"` + `aria-atomic` updates
+        // only the count text when page changes. Per spec phase-4 §2.2.
+        <div
+          className="text-muted-foreground text-sm tabular-nums"
+          aria-live="polite"
+          aria-atomic="true"
+        >
+          Showing {start}–{end} of {totalItems}
+        </div>
+      ) : (
+        <span />
+      )}
+
+      <PaginationContent>
+        {showFirstLast ? (
+          <PaginationItem>
+            <PaginationFirst size={size} onClick={onFirst} disabled={isDisabled || page <= 1} />
+          </PaginationItem>
+        ) : null}
+        <PaginationItem>
+          <PaginationPrevious size={size} onClick={onPrev} disabled={isDisabled || page <= 1} />
+        </PaginationItem>
+
+        {pages.map((p) =>
+          typeof p === "number" ? (
+            <PaginationItem key={p}>
+              <PaginationLink
+                size={size}
+                isActive={p === page}
+                aria-label={`Go to page ${p}`}
+                disabled={isDisabled}
+                onClick={() => onPageChange(p)}
+              >
+                {p}
+              </PaginationLink>
+            </PaginationItem>
+          ) : (
+            <PaginationItem key={p}>
+              <PaginationEllipsis />
+            </PaginationItem>
+          ),
+        )}
+
+        <PaginationItem>
+          <PaginationNext size={size} onClick={onNext} disabled={isDisabled || page >= pageCount} />
+        </PaginationItem>
+        {showFirstLast ? (
+          <PaginationItem>
+            <PaginationLast
+              size={size}
+              onClick={onLast}
+              disabled={isDisabled || page >= pageCount}
+            />
+          </PaginationItem>
+        ) : null}
+      </PaginationContent>
+
+      {showSizeSelector ? (
+        <Select
+          value={String(pageSize)}
+          onValueChange={(v) => onPageSizeChange?.(Number(v))}
+          disabled={isDisabled}
+        >
+          <SelectTrigger size={size} aria-label="Rows per page" className="w-auto">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            {pageSizeOptions.map((opt) => (
+              <SelectItem key={opt} value={String(opt)}>
+                {opt} per page
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      ) : (
+        <span />
+      )}
+    </Pagination>
+  );
+});
+DataPagination.displayName = "DataPagination";
+
+export {
+  Pagination,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationPrevious,
+  PaginationNext,
+  PaginationFirst,
+  PaginationLast,
+  PaginationEllipsis,
+  DataPagination,
+  paginationLinkVariants,
+};
+export type { PaginationLinkProps, PaginationDirectionalProps, DataPaginationProps };

package/components/ui/popover.stories.tsx

@@ -0,0 +1,212 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { RiInformationLine } from "@remixicon/react";
+
+import { Button } from "./button";
+import { Input } from "./input";
+import { Label } from "./label";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "./popover";
+
+const meta: Meta<typeof Popover> = {
+  title: "Foundations/Popover",
+  component: Popover,
+  parameters: { layout: "centered" },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {
+  render: () => (
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button variant="outline">Open popover</Button>
+      </PopoverTrigger>
+      <PopoverContent>
+        <div className="space-y-2">
+          <h3 className="text-sm font-semibold">Quick note</h3>
+          <p className="text-sm text-muted-foreground">
+            Popovers are non-modal floating panels.
+          </p>
+        </div>
+      </PopoverContent>
+    </Popover>
+  ),
+};
+
+export const Sides: Story = {
+  render: () => (
+    <div className="grid grid-cols-2 gap-12">
+      {(["top", "right", "bottom", "left"] as const).map((side) => (
+        <Popover key={side}>
+          <PopoverTrigger asChild>
+            <Button variant="outline" size="sm">
+              side=&quot;{side}&quot;
+            </Button>
+          </PopoverTrigger>
+          <PopoverContent side={side} width="fit">
+            <p className="text-sm">Anchored {side}.</p>
+          </PopoverContent>
+        </Popover>
+      ))}
+    </div>
+  ),
+};
+
+export const Aligns: Story = {
+  render: () => (
+    <div className="flex gap-4">
+      {(["start", "center", "end"] as const).map((align) => (
+        <Popover key={align}>
+          <PopoverTrigger asChild>
+            <Button variant="outline" size="sm">
+              align=&quot;{align}&quot;
+            </Button>
+          </PopoverTrigger>
+          <PopoverContent align={align} width="fit">
+            <p className="text-sm">align={align}</p>
+          </PopoverContent>
+        </Popover>
+      ))}
+    </div>
+  ),
+};
+
+export const WithArrow: Story = {
+  render: () => (
+    <Popover defaultOpen>
+      <PopoverTrigger asChild>
+        <Button variant="outline">With arrow</Button>
+      </PopoverTrigger>
+      <PopoverContent arrow>
+        <p className="text-sm">An arrow points at the trigger.</p>
+      </PopoverContent>
+    </Popover>
+  ),
+};
+
+export const WidthFit: Story = {
+  render: () => (
+    <Popover defaultOpen>
+      <PopoverTrigger asChild>
+        <Button variant="outline">width=&quot;fit&quot;</Button>
+      </PopoverTrigger>
+      <PopoverContent width="fit">
+        <p className="text-sm whitespace-nowrap">Sized to content width.</p>
+      </PopoverContent>
+    </Popover>
+  ),
+};
+
+export const WidthTrigger: Story = {
+  render: () => (
+    <Popover defaultOpen>
+      <PopoverTrigger asChild>
+        <Button variant="outline" className="w-72">
+          width=&quot;trigger&quot; (button is 18rem)
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent width="trigger">
+        <p className="text-sm">Matches the trigger width.</p>
+      </PopoverContent>
+    </Popover>
+  ),
+};
+
+export const WidthPresets: Story = {
+  render: () => (
+    <div className="flex gap-3">
+      {(["sm", "md", "lg", "xl"] as const).map((w) => (
+        <Popover key={w}>
+          <PopoverTrigger asChild>
+            <Button variant="outline" size="sm">
+              {w}
+            </Button>
+          </PopoverTrigger>
+          <PopoverContent width={w}>
+            <p className="text-sm">width=&quot;{w}&quot;</p>
+          </PopoverContent>
+        </Popover>
+      ))}
+    </div>
+  ),
+};
+
+export const ScrollableMaxHeight: Story = {
+  render: () => (
+    <Popover defaultOpen>
+      <PopoverTrigger asChild>
+        <Button variant="outline">maxHeight=200</Button>
+      </PopoverTrigger>
+      <PopoverContent width="md" maxHeight={200}>
+        <ul className="space-y-2 text-sm">
+          {Array.from({ length: 20 }).map((_, i) => (
+            <li key={i}>Item {i + 1}</li>
+          ))}
+        </ul>
+      </PopoverContent>
+    </Popover>
+  ),
+};
+
+export const FormInside: Story = {
+  render: () => (
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button>Edit dimensions</Button>
+      </PopoverTrigger>
+      <PopoverContent width="md">
+        <div className="space-y-3">
+          <div className="space-y-1">
+            <Label htmlFor="width" size="sm">
+              Width
+            </Label>
+            <Input id="width" type="number" defaultValue="100" size="sm" />
+          </div>
+          <div className="space-y-1">
+            <Label htmlFor="height" size="sm">
+              Height
+            </Label>
+            <Input id="height" type="number" defaultValue="100" size="sm" />
+          </div>
+        </div>
+      </PopoverContent>
+    </Popover>
+  ),
+};
+
+export const Loading: Story = {
+  render: () => (
+    <Popover defaultOpen>
+      <PopoverTrigger asChild>
+        <Button variant="outline">
+          <RiInformationLine />
+          Loading
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent width="md" loading />
+    </Popover>
+  ),
+};
+
+export const PaddingScale: Story = {
+  render: () => (
+    <div className="flex gap-3">
+      {(["none", "sm", "md", "lg"] as const).map((p) => (
+        <Popover key={p}>
+          <PopoverTrigger asChild>
+            <Button variant="outline" size="sm">
+              {p}
+            </Button>
+          </PopoverTrigger>
+          <PopoverContent padding={p}>
+            <p className="text-sm">padding=&quot;{p}&quot;</p>
+          </PopoverContent>
+        </Popover>
+      ))}
+    </div>
+  ),
+};