@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/ui/components/table.tsx

@@ -0,0 +1,506 @@
+import type { ComponentChildren, JSX } from "preact";
+import { useState } from "preact/hooks";
+
+import { cn, type ElementProps } from "../utils.ts";
+import { buttonVariants } from "./button.tsx";
+import {
+  CaretDownIcon,
+  CaretLeftIcon,
+  CaretRightIcon,
+  CaretUpDownIcon,
+  CaretUpIcon,
+} from "./icons.tsx";
+import {
+  clampPage,
+  pageCount,
+  pageSlice,
+  pageSummary,
+  pageWindow,
+  type SortDirection,
+  type SortState,
+  type SortValue,
+  sortRows,
+  toggleSort,
+} from "./table-view.ts";
+
+// Data table, ported from shadcn's Table (`data-slot="table"`). Plain HTML —
+// there is no Ark primitive to wrap — so the port is the styling only, plus
+// three additions shadcn has no answer for.
+//
+// 1. `<Table>` is two boxes: an outer card that clips, and an inner viewport
+//    that scrolls sideways. Scrolling has to live inside the card or the page
+//    body scrolls sideways instead — and the card has to be its own box or
+//    `footer` (the pager) has nowhere to sit that isn't inside the scroller.
+// 2. `truncate` on a cell + `width` on a head. Auto table layout hands a long
+//    unbroken value all the width it asks for and wraps the short columns
+//    instead; `max-w-0` on the cell caps that greed and the inner div clips,
+//    while `width` on the head states the intent up front. `layout="fixed"`
+//    is the stronger form when every column is known.
+// 3. Sorting and paging. Both are controlled: the caller owns the state, and
+//    `TableHead` / `TablePagination` render anchors or buttons depending on
+//    which callback they were handed. A plain Fresh route that never hydrates
+//    (`/admin/audit`) drives them with `<a href>` and query params; a widget
+//    or island drives them with `useTableView`. The rules behind both live in
+//    `table-view.ts`, so neither path owns a decision the other doesn't have.
+
+type TableProps = ElementProps<"table"> & {
+  /** `fixed` sizes columns from the header row alone, ignoring cell content. */
+  layout?: "auto" | "fixed";
+  /**
+   * Rendered under the scroll viewport, inside the card. A `<TablePagination>`
+   * in practice.
+   *
+   * Not a `<tfoot>`: a tfoot lives inside the scroll viewport, so on a table
+   * wide enough to scroll the pager sits off the right edge until you find it,
+   * and under `layout="fixed"` it inherits the header's column widths, so a
+   * full-width bar needs a `colSpan` every call site has to keep in step.
+   */
+  footer?: ComponentChildren;
+  /**
+   * Fill the parent's height and scroll inside, with the header pinned.
+   *
+   * Sticky is folded in here rather than being its own prop because the card
+   * clips: a sticky header is only reachable when the viewport is the thing
+   * that scrolls. A header that scrolls away in a filled table leaves a screen
+   * of unlabelled columns.
+   */
+  fill?: boolean;
+  /** `compact` tightens cell padding and drops to `text-xs`, for dense monitors. */
+  density?: "default" | "compact";
+};
+
+function Table({
+  className,
+  layout = "auto",
+  density = "default",
+  fill,
+  footer,
+  ...props
+}: TableProps) {
+  return (
+    // The split is visually a no-op for a plain table: `overflow-x: auto`
+    // already forces `overflow-y` to compute to `auto`, and `overflow: hidden`
+    // here clips at the same padding box — the rounded corners still cut the
+    // header's tint, and the scrollbar still sits inside the border.
+    <div
+      data-slot="table-card"
+      className={cn(
+        "w-full overflow-hidden rounded-2xl border border-border bg-card",
+        fill && "flex h-full min-h-0 flex-col",
+      )}
+    >
+      <div
+        data-slot="table-container"
+        className={cn("w-full overflow-x-auto", fill && "min-h-0 flex-1 overflow-auto")}
+      >
+        <table
+          data-slot="table"
+          data-layout={layout}
+          data-density={density}
+          data-fill={fill ? "true" : undefined}
+          className={cn(
+            "w-full text-sm data-[layout=fixed]:table-fixed data-[density=compact]:text-xs",
+            className,
+          )}
+          {...props}
+        />
+      </div>
+      {footer}
+    </div>
+  );
+}
+
+function TableHeader({ className, ...props }: ElementProps<"thead">) {
+  return (
+    <thead
+      data-slot="table-header"
+      className={cn(
+        "bg-muted/40 text-xs uppercase tracking-wide text-muted-foreground",
+        // Under `fill` the viewport is the scroller, so the header pins to it.
+        // Read off the table's `data-fill` rather than a prop, which keeps the
+        // three leaf components stateless and prop-free.
+        "[[data-fill]_&]:sticky [[data-fill]_&]:top-0 [[data-fill]_&]:z-10 [[data-fill]_&]:bg-muted/60 [[data-fill]_&]:backdrop-blur",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function TableBody({ className, ...props }: ElementProps<"tbody">) {
+  return <tbody data-slot="table-body" className={cn(className)} {...props} />;
+}
+
+function TableRow({ className, ...props }: ElementProps<"tr">) {
+  return (
+    <tr
+      data-slot="table-row"
+      className={cn("border-t border-border first:border-t-0", className)}
+      {...props}
+    />
+  );
+}
+
+type TableHeadProps = ElementProps<"th"> & {
+  /** Any CSS length or percentage. A hint under `auto`, binding under `fixed`. */
+  width?: string;
+  /** This column's direction, or `null` for "sortable, but not the sort". */
+  sorted?: SortDirection | null;
+  /** Renders the label as an `<a>`. The only form that works unhydrated. */
+  sortHref?: string;
+  /** Renders the label as a `<button>`. Ignored when `sortHref` is given. */
+  onSort?: (event: JSX.TargetedMouseEvent<HTMLElement>) => void;
+};
+
+const ARIA_SORT = { asc: "ascending", desc: "descending" } as const;
+
+function TableHead({
+  className,
+  width,
+  style,
+  sorted = null,
+  sortHref,
+  onSort,
+  children,
+  ...props
+}: TableHeadProps) {
+  const sortable = sortHref !== undefined || onSort !== undefined;
+  // The trigger is the label, not the `<th>`: a click target covering a 14rem
+  // cell fires on dead space, and a `<th>` is not keyboard reachable however
+  // many handlers it carries.
+  //
+  // `-mx-1.5` cancels the trigger's own padding, so a sortable label sits on
+  // the same pixel as a plain one in the header beside it.
+  const triggerClass = cn(
+    "group/sort -mx-1.5 inline-flex max-w-full cursor-pointer items-center gap-1 rounded-md px-1.5 py-0.5 text-left align-middle outline-none transition-colors hover:text-foreground focus-visible:ring-3 focus-visible:ring-ring/50",
+    sorted && "text-foreground",
+  );
+  const caret =
+    sorted === "asc" ? (
+      <CaretUpIcon className="size-3 shrink-0" />
+    ) : sorted === "desc" ? (
+      <CaretDownIcon className="size-3 shrink-0" />
+    ) : (
+      // Revealed on hover rather than always drawn: six permanent arrows compete
+      // with the one that says what the sort actually is. `opacity-0` and not
+      // `hidden`, so the column doesn't jump wider the moment it becomes sorted.
+      <CaretUpDownIcon className="size-3 shrink-0 opacity-0 transition-opacity group-hover/sort:opacity-60" />
+    );
+  return (
+    <th
+      data-slot="table-head"
+      // "none" rather than omitted on the unsorted columns: that is what tells
+      // a screen reader the other headers are sortable at all.
+      aria-sort={sortable ? (sorted ? ARIA_SORT[sorted] : "none") : undefined}
+      style={width ? { width, ...(style as Record<string, unknown>) } : style}
+      className={cn(
+        "whitespace-nowrap px-4 py-2.5 text-left font-semibold",
+        "[[data-density=compact]_&]:px-3 [[data-density=compact]_&]:py-2",
+        className,
+      )}
+      {...props}
+    >
+      {!sortable ? (
+        children
+      ) : sortHref !== undefined ? (
+        // `data-sorted` and not the glyph: an e2e selector shouldn't depend on
+        // which caret rendered.
+        <a
+          href={sortHref}
+          data-slot="table-sort"
+          data-sorted={sorted ?? "none"}
+          class={triggerClass}
+        >
+          {children}
+          {caret}
+        </a>
+      ) : (
+        <button
+          type="button"
+          data-slot="table-sort"
+          data-sorted={sorted ?? "none"}
+          class={triggerClass}
+          onClick={onSort}
+        >
+          {children}
+          {caret}
+        </button>
+      )}
+    </th>
+  );
+}
+
+type TableCellProps = ElementProps<"td"> & {
+  /** Clip to one line with an ellipsis instead of wrapping. Sets `title` from `text`. */
+  truncate?: boolean;
+  /** Tooltip + ellipsis source when the cell's children aren't a plain string. */
+  text?: string;
+};
+
+function TableCell({ className, truncate, text, children, ...props }: TableCellProps) {
+  const title = text ?? (typeof children === "string" ? children : undefined);
+  return (
+    <td
+      data-slot="table-cell"
+      // max-w-0 stops an auto-layout column claiming width from its content;
+      // the cap is the share the header widths leave it, and the inner div
+      // clips to that. Without it `truncate` on the cell alone does nothing.
+      className={cn(
+        "px-4 py-3 align-middle",
+        "[[data-density=compact]_&]:px-3 [[data-density=compact]_&]:py-1",
+        truncate && "max-w-0",
+        className,
+      )}
+      {...props}
+    >
+      {truncate ? (
+        <div class="truncate" title={title}>
+          {children}
+        </div>
+      ) : (
+        children
+      )}
+    </td>
+  );
+}
+
+type PageControlProps = {
+  page: number;
+  label: string;
+  /** The page being rendered is the one on screen. */
+  current?: boolean;
+  /** No such page. Renders inert markup, never a link. */
+  disabled?: boolean;
+  hrefFor?: (page: number) => string;
+  onPageChange?: (page: number) => void;
+  children: ComponentChildren;
+};
+
+function PageControl({
+  page,
+  label,
+  current,
+  disabled,
+  hrefFor,
+  onPageChange,
+  children,
+}: PageControlProps) {
+  const className = cn(
+    buttonVariants({ variant: current ? "secondary" : "ghost", size: "xs" }),
+    // tabular-nums + a floor on the width so the box doesn't resize between
+    // 9 and 10 and shuffle every control after it.
+    "min-w-7 justify-center tabular-nums",
+  );
+  // A dead control is a `<span>`, never an anchor: anchors have no `disabled`,
+  // `pointer-events-none` does nothing for the keyboard, and an `href` that
+  // names a page which doesn't exist is a link that lies.
+  if (disabled || current) {
+    return (
+      <span
+        aria-current={current ? "page" : undefined}
+        aria-disabled={disabled ? "true" : undefined}
+        aria-label={current ? undefined : label}
+        className={cn(className, disabled && "opacity-40")}
+      >
+        {children}
+      </span>
+    );
+  }
+  if (hrefFor) {
+    return (
+      // `aria-current="false"` is spelled out rather than left off: Fresh stamps
+      // its own `aria-current` onto every root-relative `<a>` whose PATH matches
+      // the current one, backing off only when the prop is already set
+      // (`setActiveUrl` in fresh/runtime). Every control in a pager shares that
+      // path and differs only in the query, so without this Fresh marks them all
+      // and announces a control the reader is NOT on as the current page.
+      // "false" is the ARIA default, so it is inert everywhere else.
+      <a href={hrefFor(page)} aria-label={label} aria-current="false" className={className}>
+        {children}
+      </a>
+    );
+  }
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      className={className}
+      onClick={() => onPageChange?.(page)}
+    >
+      {children}
+    </button>
+  );
+}
+
+type TablePaginationBase = {
+  page: number;
+  pageSize: number;
+  total: number;
+  /** Pages either side of the current one. The row is `2 * siblings + 5` wide. */
+  siblings?: number;
+  /** Extra controls between the summary and the nav, e.g. a rows-per-page picker. */
+  children?: ComponentChildren;
+  className?: string;
+};
+
+/**
+ * The pager, for `<Table footer={...}>`.
+ *
+ * Exactly one of `hrefFor` / `onPageChange`, enforced in the type: a pager that
+ * looks live and does nothing is a compile error rather than a bug report. There
+ * is no `pageCount` prop either — it derives from `total` and `pageSize`, and two
+ * inputs that can disagree is one too many.
+ */
+type TablePaginationProps = TablePaginationBase &
+  (
+    | { hrefFor: (page: number) => string; onPageChange?: never }
+    | { onPageChange: (page: number) => void; hrefFor?: never }
+  );
+
+function TablePagination({
+  page,
+  pageSize,
+  total,
+  siblings = 1,
+  children,
+  className,
+  hrefFor,
+  onPageChange,
+}: TablePaginationProps) {
+  const count = pageCount(total, pageSize);
+  const current = clampPage(page, count);
+  const pages = pageWindow(current, count, siblings);
+  return (
+    <div
+      data-slot="table-pagination"
+      className={cn(
+        "flex flex-wrap items-center justify-between gap-3 border-t border-border px-4 py-2 text-xs text-muted-foreground",
+        className,
+      )}
+    >
+      <span data-slot="table-pagination-summary" className="tabular-nums">
+        {pageSummary(current, pageSize, total)}
+      </span>
+      {children ? <div className="flex flex-wrap items-center gap-2">{children}</div> : null}
+      <nav aria-label="Pagination" className="flex items-center gap-1">
+        <PageControl
+          page={current - 1}
+          label="Previous page"
+          disabled={current <= 1}
+          hrefFor={hrefFor}
+          onPageChange={onPageChange}
+        >
+          <CaretLeftIcon className="size-3" />
+        </PageControl>
+        {pages.map((entry, index) =>
+          entry === "ellipsis" ? (
+            <span key={`gap-${index}`} aria-hidden="true" className="px-1">
+              …
+            </span>
+          ) : (
+            <PageControl
+              key={entry}
+              page={entry}
+              label={`Page ${entry}`}
+              current={entry === current}
+              hrefFor={hrefFor}
+              onPageChange={onPageChange}
+            >
+              {entry}
+            </PageControl>
+          ),
+        )}
+        <PageControl
+          page={current + 1}
+          label="Next page"
+          disabled={current >= count}
+          hrefFor={hrefFor}
+          onPageChange={onPageChange}
+        >
+          <CaretRightIcon className="size-3" />
+        </PageControl>
+      </nav>
+    </div>
+  );
+}
+
+export interface TableView<T, K extends string> {
+  /** The rows to render: sorted, and sliced to the current page. */
+  rows: readonly T[];
+  /** Rows before paging, which is what `TablePagination` wants. */
+  total: number;
+  page: number;
+  pageCount: number;
+  pageSize: number;
+  setPage: (page: number) => void;
+  /** This column's direction, or `null` — feeds `TableHead`'s `sorted`. */
+  sorted: (key: K) => SortDirection | null;
+  toggle: (key: K, initial?: SortDirection) => void;
+}
+
+/**
+ * Client-side sorting and paging for a hydrated table.
+ *
+ * Both halves live in one hook because "sorting resets to page 1" is the one
+ * invariant a call site can't see: an offset into a re-sorted list is noise,
+ * and splitting the hook means repeating `setPage(1)` next to every column.
+ *
+ * Safe inside a widget iframe, and deliberately so. The runtime's boot gate
+ * blanks the whole author subtree while a loader has no data and is fetching,
+ * and a loader's query key includes its `request`, so paging by `setState`
+ * would re-key the query, blank the data, trip the gate and destroy every
+ * nested component's state. Sorting and slicing what's already loaded never
+ * touches `request`, so it never fires. Page on the server only when the row
+ * count genuinely can't be held in memory.
+ *
+ * A non-island Fresh route can't use this at all — `useState` there renders its
+ * initial value and a header click does nothing. Drive `TableHead`'s `sortHref`
+ * and `TablePagination`'s `hrefFor` off query params instead, the same way
+ * `timeago.tsx` points non-islands at their own shell.
+ */
+export function useTableView<T, K extends string>(
+  rows: readonly T[],
+  options: {
+    columns: Record<K, (row: T) => SortValue>;
+    // NoInfer, or `K` gets pinned to the single key spelled here instead of the
+    // union of the `columns` literal, and every other column stops typechecking.
+    initial?: { key: NoInfer<K>; direction: SortDirection };
+    /** Omit for sort-only: rows come back whole and `pageCount` is 1. */
+    pageSize?: number;
+  },
+): TableView<T, K> {
+  const [sort, setSort] = useState<SortState | null>(options.initial ?? null);
+  const [page, setPage] = useState(1);
+
+  // No useMemo: this is O(n log n) over a list the caller then walks anyway,
+  // and the `columns` object literal every call site writes is a new identity
+  // per render, which would make the memo a permanent miss with extra steps.
+  const sorted = sortRows(rows, sort, options.columns);
+  const wanted = options.pageSize ?? 0;
+  const paged = wanted > 0;
+  const size = paged ? wanted : sorted.length;
+  const count = pageCount(sorted.length, size);
+  // Clamped on read rather than corrected in an effect: a row deleted off the
+  // end of the last page would otherwise paint one empty frame first, and
+  // inside a widget iframe that frame is a blank card. The cost is that the
+  // stored page survives the shrink, so a list that shrinks below the current
+  // page and grows back returns the reader to where they were, not where the
+  // shrink left them.
+  const current = clampPage(page, count);
+
+  return {
+    rows: paged ? pageSlice(sorted, current, size) : sorted,
+    total: sorted.length,
+    page: current,
+    pageCount: count,
+    pageSize: size,
+    setPage,
+    sorted: (key) => (sort?.key === key ? sort.direction : null),
+    toggle: (key, initial) => {
+      setSort((cur) => toggleSort(cur, key, initial));
+      setPage(1);
+    },
+  };
+}
+
+export { Table, TableBody, TableCell, TableHead, TableHeader, TablePagination, TableRow };

package/src/ui/components/tabs.tsx

@@ -0,0 +1,59 @@
+import type { ComponentProps } from "preact";
+import { Tabs as TabsPrimitive } from "@ark-ui/react/tabs";
+
+import { cn } from "../utils.ts";
+
+// shadcn-style Tabs ported onto Ark UI's tabs machine (Zag). Radix's
+// `asChild` polymorphism is dropped (preact/compat) — same convention as the
+// rest of this dir. Active styling keys off `aria-selected` (the ARIA tabs
+// attribute Zag sets on the active trigger) — NOT Radix's `data-state=active`,
+// which Ark never emits. Triggers accept arbitrary children, so a caller can
+// append a count badge next to the label.
+
+function Tabs({ className, ...props }: ComponentProps<typeof TabsPrimitive.Root>) {
+  return (
+    <TabsPrimitive.Root
+      data-slot="tabs"
+      className={cn("flex flex-col gap-3", className)}
+      {...props}
+    />
+  );
+}
+
+function TabsList({ className, ...props }: ComponentProps<typeof TabsPrimitive.List>) {
+  return (
+    <TabsPrimitive.List
+      data-slot="tabs-list"
+      className={cn(
+        "inline-flex w-fit max-w-full flex-wrap items-center gap-1 rounded-2xl bg-muted p-1 text-muted-foreground",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function TabsTrigger({ className, ...props }: ComponentProps<typeof TabsPrimitive.Trigger>) {
+  return (
+    <TabsPrimitive.Trigger
+      data-slot="tabs-trigger"
+      className={cn(
+        "inline-flex cursor-pointer items-center justify-center gap-1.5 rounded-xl px-3 py-1.5 text-sm font-medium whitespace-nowrap text-muted-foreground transition-all outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-selected:bg-card aria-selected:font-semibold aria-selected:text-foreground aria-selected:shadow",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function TabsContent({ className, ...props }: ComponentProps<typeof TabsPrimitive.Content>) {
+  return (
+    <TabsPrimitive.Content
+      data-slot="tabs-content"
+      className={cn("flex flex-col gap-3 outline-none", className)}
+      {...props}
+    />
+  );
+}
+
+export { Tabs, TabsList, TabsTrigger, TabsContent };

package/src/ui/components/timeago.tsx

@@ -0,0 +1,84 @@
+// Relative-time helper + presentational <TimeAgo /> wrapper. Renders the
+// relative string ("5 minutes ago", "in 2 days") inside an Ark Tooltip
+// that reveals the absolute UTC timestamp on hover.
+//
+// Pure render-time computation by default: we don't tick on a timer because
+// most callers either re-render naturally (island state changes) or are fine
+// with the value staying frozen until next navigation. Pass `live` for the
+// case that isn't - a duration that must advance while its subject is still
+// running, where nothing else re-renders because nothing else changed.
+//
+// The Ark Tooltip needs hydration to open; consumers rendering this in a
+// non-island Fresh route should wrap it in their own island shell (e.g.
+// `platform/home/src/islands/TimeAgo.tsx`).
+
+import { useEffect, useState } from "preact/hooks";
+
+const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
+
+const UNITS: [Intl.RelativeTimeFormatUnit, number][] = [
+  ["year", 60 * 60 * 24 * 365],
+  ["month", 60 * 60 * 24 * 30],
+  ["week", 60 * 60 * 24 * 7],
+  ["day", 60 * 60 * 24],
+  ["hour", 60 * 60],
+  ["minute", 60],
+  ["second", 1],
+];
+
+export function timeago(date: Date, now = new Date()): string {
+  const diffSeconds = (date.getTime() - now.getTime()) / 1000;
+  for (const [unit, secondsInUnit] of UNITS) {
+    if (Math.abs(diffSeconds) >= secondsInUnit || unit === "second") {
+      return rtf.format(Math.round(diffSeconds / secondsInUnit), unit);
+    }
+  }
+  return rtf.format(0, "second");
+}
+
+// Fixed locale + UTC so SSR and client produce identical strings.
+function formatAbsolute(date: Date): string {
+  return date.toLocaleString("en-US", {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+    timeZone: "UTC",
+    timeZoneName: "short",
+  });
+}
+
+import { Tooltip, TooltipContent, TooltipTrigger } from "./tooltip.tsx";
+
+export function TimeAgo({
+  value,
+  className,
+  live,
+}: {
+  value: Date | string;
+  className?: string;
+  live?: boolean;
+}) {
+  const date = typeof value === "string" ? new Date(value) : value;
+  // `timeago()` reads the clock at render, so the string only moves when
+  // something re-renders. A polled loader whose payload is unchanged doesn't
+  // re-render (the query keeps the same data by structural sharing), which is
+  // exactly the in-flight case - so `live` drives its own tick.
+  const [, tick] = useState(0);
+  useEffect(() => {
+    if (!live) return;
+    const id = setInterval(() => tick((n) => n + 1), 1000);
+    return () => clearInterval(id);
+  }, [live]);
+  return (
+    <Tooltip>
+      <TooltipTrigger>
+        <time className={className} dateTime={date.toISOString()}>
+          {timeago(date)}
+        </time>
+      </TooltipTrigger>
+      <TooltipContent side="top">{formatAbsolute(date)}</TooltipContent>
+    </Tooltip>
+  );
+}