cortena-ui 1.4.2 → 1.5.0

package/src/components/consent-screen.tsx

@@ -0,0 +1,239 @@
+"use client";
+
+import type * as React from "react";
+import { Alert, AlertDescription } from "@/components/alert";
+import { Button } from "@/components/button";
+import { AuthScreen } from "@/components/login-screen";
+import { Spinner } from "@/components/spinner";
+import { cn } from "@/lib/cn";
+
+/**
+ * ConsentScreen — the OAuth authorize page an MCP client lands on
+ * (how-to-create-a-cortena-extension §7.4, audit rule P-08, decision DESIGN-D1).
+ *
+ * It is the consent *variant* of the login screen rather than a screen of its
+ * own: same frame, same card, same tokens, same brand row. That is the whole
+ * requirement. An MCP client opens a browser onto a page nobody chose to visit,
+ * and if that page looks like a different product the only honest reading is
+ * that something has gone wrong. Sharing `AuthScreen` with `LoginScreen` is
+ * what makes the two impossible to drift apart.
+ *
+ * It replaces the hand-written HTML cortena-auth serves today
+ * (`src/routes/oauth-login.ts`, `renderConsent`), and the props are that page's
+ * contents: the client asking, the scopes it wants in plain language, who the
+ * user is signed in as, and Allow / Deny. Props-only — the flow id, the CSRF
+ * binding cookie, the double-submit guard and the redirect all stay on the
+ * server, where they already work.
+ */
+
+export interface ConsentClient {
+  /** The registered client name — "Claude Code". Never the raw client id. */
+  name: string;
+  /**
+   * The client's own logo, when it registered one. **https only** — the value
+   * is a third party's, and this is the screen on which a user decides whether
+   * to give that third party access, so `AuthScreen` drops a `data:`, `blob:`
+   * or `http:` URL and draws the mark instead (`httpsLogoUrl`).
+   */
+  logoUrl?: string;
+}
+
+export interface ConsentScope {
+  /** The raw scope string, `task:read`. Shown, small, under the label. */
+  id: string;
+  /** The plain-language gloss — cortena-auth's `glossFor(scope)`. */
+  label: string;
+  /** One sentence on what granting it actually allows. */
+  description?: string;
+}
+
+export interface ConsentUser {
+  name: string;
+  email: string;
+}
+
+export interface ConsentScreenProps extends Omit<React.ComponentProps<"div">, "onSubmit"> {
+  client: ConsentClient;
+  /**
+   * The requested scopes, already glossed. Rendered in the order given, which
+   * is the order cortena-auth resolved them in — not re-sorted here, so the
+   * screen and the granted token read the same way.
+   */
+  scopes: readonly ConsentScope[];
+  /** Who is about to grant this. Shown, because consent is personal. */
+  user: ConsentUser;
+  onAllow?: () => void;
+  onDeny?: () => void;
+  /** Disables both decisions and marks Allow busy. One decision per page. */
+  loading?: boolean;
+  /** A failed decision, in the user's words. */
+  error?: string;
+}
+
+function ConsentScreen({
+  className,
+  client,
+  scopes,
+  user,
+  onAllow,
+  onDeny,
+  loading,
+  error,
+  ...props
+}: ConsentScreenProps) {
+  return (
+    <AuthScreen
+      data-slot="consent-screen"
+      data-loading={loading ? "" : undefined}
+      className={className}
+      brand={{ name: client.name, logoUrl: client.logoUrl }}
+      title={`${client.name} wants access`}
+      subtitle="Review what it is asking for before you allow it."
+      notices={
+        error ? (
+          <Alert variant="destructive" data-slot="consent-screen-error">
+            <AlertDescription className="text-[color:var(--ds-foreground)]">
+              {error}
+            </AlertDescription>
+          </Alert>
+        ) : null
+      }
+      footer={
+        <span data-slot="consent-screen-footer">
+          You can revoke this access at any time from your Cortena settings.
+        </span>
+      }
+      {...props}
+    >
+      <div
+        data-slot="consent-screen-user"
+        className={cn(
+          "flex flex-col gap-0.5 rounded-[var(--ds-radius-md)] bg-[var(--ds-muted)] px-3.5 py-3",
+          "text-[length:var(--ds-text-caption-lg)]",
+          "leading-[var(--ds-text-caption-lg--line-height)]",
+        )}
+      >
+        <span className="font-medium text-[color:var(--ds-foreground)]">
+          Signed in as {user.name}
+        </span>
+        <span className="text-[color:var(--ds-muted-foreground)]">{user.email}</span>
+      </div>
+
+      <div data-slot="consent-screen-scopes" className="flex flex-col gap-2">
+        <p
+          className={cn(
+            "text-[length:var(--ds-text-caption)]",
+            "leading-[var(--ds-text-caption--line-height)]",
+            "text-[color:var(--ds-muted-foreground)]",
+          )}
+        >
+          {client.name} will be able to:
+        </p>
+        {/* An empty list is a real state: a client can ask for no scopes at
+            all, and saying so is better than an empty box the user has to
+            interpret. */}
+        {scopes.length === 0 ? (
+          <p
+            data-slot="consent-screen-no-scopes"
+            className={cn(
+              "text-[length:var(--ds-text-caption-lg)]",
+              "leading-[var(--ds-text-caption-lg--line-height)]",
+              "text-[color:var(--ds-muted-foreground)]",
+            )}
+          >
+            Nothing beyond confirming who you are.
+          </p>
+        ) : (
+          <ul className="flex list-none flex-col gap-2.5 p-0">
+            {scopes.map((scope) => (
+              <li
+                key={scope.id}
+                data-slot="consent-scope"
+                data-scope={scope.id}
+                className="flex gap-2.5"
+              >
+                <CheckGlyph />
+                <span className="flex min-w-0 flex-col gap-0.5">
+                  <span
+                    className={cn(
+                      "font-medium text-[length:var(--ds-text-caption-lg)]",
+                      "leading-[var(--ds-text-caption-lg--line-height)]",
+                      "text-[color:var(--ds-foreground)]",
+                    )}
+                  >
+                    {scope.label}
+                  </span>
+                  {scope.description ? (
+                    <span
+                      className={cn(
+                        "text-[length:var(--ds-text-caption)]",
+                        "leading-[var(--ds-text-caption--line-height)]",
+                        "text-[color:var(--ds-muted-foreground)]",
+                      )}
+                    >
+                      {scope.description}
+                    </span>
+                  ) : null}
+                  <span
+                    className={cn(
+                      "font-mono text-[length:var(--ds-text-caption-sm)]",
+                      "text-[color:var(--ds-text-tertiary)]",
+                    )}
+                  >
+                    {scope.id}
+                  </span>
+                </span>
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+
+      {/* Allow first and filled, Deny second and quiet — but both are real
+          buttons of the same size, so declining is never the harder click. */}
+      <div data-slot="consent-screen-actions" className="flex flex-col gap-2.5">
+        <Button
+          type="button"
+          size="lg"
+          disabled={loading}
+          data-decision="allow"
+          onClick={onAllow}
+        >
+          {loading ? <Spinner tone="inverse" /> : null}
+          {loading ? "Allowing…" : "Allow"}
+        </Button>
+        <Button
+          type="button"
+          variant="secondary"
+          size="lg"
+          disabled={loading}
+          data-decision="deny"
+          onClick={onDeny}
+        >
+          Deny
+        </Button>
+      </div>
+    </AuthScreen>
+  );
+}
+
+/** The scope bullet. Inline rather than a lucide import: one icon, one size. */
+function CheckGlyph() {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+      focusable="false"
+      className="mt-0.5 size-4 shrink-0 text-[color:var(--ds-primary)]"
+    >
+      <path d="m4 12.5 5 5L20 6.5" />
+    </svg>
+  );
+}
+
+export { ConsentScreen };

package/src/components/data-table/data-table.tsx

@@ -44,8 +44,23 @@ const VIRTUALIZE_ABOVE = 100;
 const DEFAULT_VIRTUAL_HEIGHT = 600;
 const INFINITE_THRESHOLD_PX = 240;
 
+/** What a `ref` on `DataTable` hands back. */
+export interface DataTableHandle<Row extends RowData> {
+  /**
+   * Refetch the page on screen through the same query the auto-refresh
+   * interval drives — never a second fetch path. A table subscribed to a
+   * notification stream calls this from the stream and leaves the interval as
+   * the fallback for when the stream is unavailable.
+   */
+  refresh: () => void;
+  /** Everything else the table knows, for a caller that needs more than a refresh. */
+  instance: DataTableInstance<Row>;
+}
+
 export interface DataTableViewProps<Row extends RowData> {
   className?: string;
+  /** Imperative handle: `ref.current.refresh()`. */
+  ref?: React.Ref<DataTableHandle<Row>>;
   /** Height of the scrolling body. Required for virtualisation to mean anything; defaults to 600px when virtualised. */
   maxHeight?: number | string;
   /** Force virtualisation on or off; undefined virtualises above 100 rows. */
@@ -124,6 +139,7 @@ function DataTableOwned<Row extends RowData>(props: DataTableViewProps<Row> & Us
     onRowClick,
     activeRowId,
     rowClassName,
+    ref,
     ...options
   } = props;
   const instance = useDataTable<Row>({
@@ -154,6 +170,7 @@ function DataTableOwned<Row extends RowData>(props: DataTableViewProps<Row> & Us
       onRowClick={onRowClick}
       activeRowId={activeRowId}
       rowClassName={rowClassName}
+      ref={ref}
     />
   );
 }
@@ -275,6 +292,7 @@ function DataTableView<Row extends RowData>({
   onRowClick,
   activeRowId,
   rowClassName,
+  ref,
 }: DataTableViewProps<Row> & { instance: DataTableInstance<Row> }) {
   const { table, paginationMode } = instance;
   const rows = table.getRowModel().rows;
@@ -291,6 +309,23 @@ function DataTableView<Row extends RowData>({
   const scrollRef = React.useRef<HTMLDivElement>(null);
   const tableRef = React.useRef<HTMLTableElement>(null);
 
+  const refresh = instance.refetch;
+  React.useImperativeHandle(ref, () => ({ refresh, instance }), [refresh, instance]);
+
+  // Mandatory on every server-backed table (P-39): a Refresh button beside the
+  // search box and a stamp saying which moment these rows are. The switch only
+  // appears where the table asked for `autoRefresh`.
+  const refreshProps =
+    instance.dataSource.kind === "server"
+      ? {
+          onRefresh: refresh,
+          isFetching: instance.isFetching,
+          lastUpdatedAt: instance.lastUpdatedAt,
+          lastErrorAt: instance.lastErrorAt,
+          autoRefresh: instance.autoRefresh,
+        }
+      : undefined;
+
   /* Virtualisation ------------------------------------------------------ */
 
   const virtualizer = useVirtualizer<HTMLDivElement, HTMLTableRowElement>({
@@ -587,6 +622,7 @@ function DataTableView<Row extends RowData>({
           searchPlaceholder={searchPlaceholder}
           enableExport={enableExport}
           exportFileName={exportFileName}
+          refresh={refreshProps}
         >
           {toolbarActions}
         </DataTableToolbar>

package/src/components/data-table/index.tsx

@@ -1,12 +1,13 @@
 "use client";
 
 export { DataTable, DataTableView } from "./data-table";
-export type { DataTableProps, DataTableViewProps } from "./data-table";
+export type { DataTableHandle, DataTableProps, DataTableViewProps } from "./data-table";
 export {
   DataTableColumnHeader,
   DataTableExportMenu,
   DataTableFacetedFilter,
   DataTablePagination,
+  DataTableRefresh,
   DataTableToolbar,
   DataTableViewOptions,
 } from "./parts";
@@ -16,6 +17,7 @@ export type {
   DataTableFacetedFilterOption,
   DataTableFacetedFilterProps,
   DataTablePaginationProps,
+  DataTableRefreshProps,
   DataTableToolbarProps,
   DataTableViewOptionsProps,
 } from "./parts";
@@ -27,6 +29,8 @@ export type { ExportCell, ExportSheet } from "./export";
 export type {
   ClientSource,
   DataSource,
+  DataTableAutoRefresh,
+  DataTableAutoRefreshState,
   DataTableCell,
   DataTableColumn,
   DataTableColumnDef,
@@ -35,6 +39,7 @@ export type {
   DataTableEditingCell,
   DataTableInstance,
   DataTablePaginationMode,
+  DataTableRefreshPause,
   DataTableRow,
   DataTableState,
   DataTableTable,

package/src/components/data-table/parts.tsx

@@ -14,6 +14,7 @@ import {
   EyeOff,
   ListFilter,
   PinOff,
+  RefreshCw,
   Search,
   Settings2,
   X,
@@ -32,9 +33,11 @@ import {
 } from "@/components/dropdown-menu";
 import { Input } from "@/components/input";
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/select";
+import { StatusDot } from "@/components/status-dot";
+import { Switch } from "@/components/switch";
 import { cn } from "@/lib/cn";
 import { columnLabel, downloadCsv, downloadExcel } from "./export";
-import type { DataTableColumn, DataTableTable } from "./types";
+import type { DataTableAutoRefreshState, DataTableColumn, DataTableTable } from "./types";
 
 /* ------------------------------------------------------------------------ */
 /* Column header                                                             */
@@ -404,6 +407,11 @@ export interface DataTableToolbarProps<Row extends RowData>
   /** @default true */
   enableExport?: boolean;
   exportFileName?: string;
+  /**
+   * Freshness controls beside the search box. `DataTable` fills this in for
+   * every server source; a hand-built toolbar must pass it too (P-39).
+   */
+  refresh?: DataTableRefreshProps;
 }
 
 /**
@@ -418,6 +426,7 @@ function DataTableToolbar<Row extends RowData>({
   children,
   enableExport = true,
   exportFileName,
+  refresh,
   className,
   ...props
 }: DataTableToolbarProps<Row>) {
@@ -435,54 +444,59 @@ function DataTableToolbar<Row extends RowData>({
       className={cn("flex flex-wrap items-center gap-2", className)}
       {...props}
     >
-      {selectedRows.length ? (
-        <div data-slot="data-table-bulk-actions" className="flex min-w-0 flex-1 flex-wrap items-center gap-2">
-          <span className="text-[length:var(--ds-text-caption-lg)] text-[color:var(--ds-muted-foreground)]">
-            <span className="font-medium text-[color:var(--ds-foreground)]">{selectedRows.length}</span> selected
-          </span>
-          {bulkActions?.({ rows: selectedRows.map((r) => r.original), table })}
-          <Button variant="ghost" size="sm" onClick={() => table.resetRowSelection()}>
-            Clear
-            <X />
-          </Button>
-        </div>
-      ) : (
-        <div className="flex min-w-0 flex-1 flex-wrap items-center gap-2">
-          {canSearch ? (
-            <div className="relative w-full max-w-64">
-              <Search
-                aria-hidden
-                className="pointer-events-none absolute left-2.5 top-1/2 size-4 -translate-y-1/2 text-[color:var(--ds-text-tertiary)]"
-              />
-              <Input
-                data-slot="data-table-search"
-                type="search"
-                aria-label="Search"
-                placeholder={searchPlaceholder}
-                value={globalFilter}
-                onChange={(e) => table.setGlobalFilter(e.target.value)}
-                className="h-8 pl-8 text-[length:var(--ds-text-caption-lg)]"
-              />
-            </div>
-          ) : null}
-          {facetedColumns.map((column) => (
-            <DataTableFacetedFilter key={column.id} column={column} />
-          ))}
-          {isFiltered ? (
-            <Button
-              variant="ghost"
-              size="sm"
-              onClick={() => {
-                table.resetColumnFilters();
-                table.setGlobalFilter("");
-              }}
-            >
-              Reset
+      <div className="flex min-w-0 flex-1 flex-wrap items-center gap-2">
+        {selectedRows.length ? (
+          <div data-slot="data-table-bulk-actions" className="flex min-w-0 flex-wrap items-center gap-2">
+            <span className="text-[length:var(--ds-text-caption-lg)] text-[color:var(--ds-muted-foreground)]">
+              <span className="font-medium text-[color:var(--ds-foreground)]">{selectedRows.length}</span> selected
+            </span>
+            {bulkActions?.({ rows: selectedRows.map((r) => r.original), table })}
+            <Button variant="ghost" size="sm" onClick={() => table.resetRowSelection()}>
+              Clear
               <X />
             </Button>
-          ) : null}
-        </div>
-      )}
+          </div>
+        ) : (
+          <div className="flex min-w-0 flex-wrap items-center gap-2">
+            {canSearch ? (
+              <div className="relative w-64 max-w-full">
+                <Search
+                  aria-hidden
+                  className="pointer-events-none absolute left-2.5 top-1/2 size-4 -translate-y-1/2 text-[color:var(--ds-text-tertiary)]"
+                />
+                <Input
+                  data-slot="data-table-search"
+                  type="search"
+                  aria-label="Search"
+                  placeholder={searchPlaceholder}
+                  value={globalFilter}
+                  onChange={(e) => table.setGlobalFilter(e.target.value)}
+                  className="h-8 pl-8 text-[length:var(--ds-text-caption-lg)]"
+                />
+              </div>
+            ) : null}
+            {facetedColumns.map((column) => (
+              <DataTableFacetedFilter key={column.id} column={column} />
+            ))}
+            {isFiltered ? (
+              <Button
+                variant="ghost"
+                size="sm"
+                onClick={() => {
+                  table.resetColumnFilters();
+                  table.setGlobalFilter("");
+                }}
+              >
+                Reset
+                <X />
+              </Button>
+            ) : null}
+          </div>
+        )}
+        {/* Beside the search box, and still there while a selection is up: the
+            stamp answers "how old is this?", which a selection does not change. */}
+        {refresh ? <DataTableRefresh {...refresh} /> : null}
+      </div>
       <div className="flex items-center gap-2">
         {children}
         <DataTableViewOptions table={table} />
@@ -492,6 +506,167 @@ function DataTableToolbar<Row extends RowData>({
   );
 }
 
+/* ------------------------------------------------------------------------ */
+/* Refresh + freshness stamp                                                 */
+/* ------------------------------------------------------------------------ */
+
+/** A failed background refresh says so beside the stamp, then gets out of the way. */
+const ERROR_VISIBLE_MS = 10_000;
+/** Under a minute the stamp is relative; past it, the clock time it was taken. */
+const RELATIVE_WINDOW_MS = 60_000;
+
+/**
+ * Re-renders once, at a moment named in advance.
+ *
+ * The stamp has exactly two of them — the minute at which "just now" stops
+ * being true, and the ten seconds a failure is worth mentioning — and neither
+ * is a good reason to tick on a timer: a clock time, once shown, never changes
+ * again, so a periodic re-render would be one every fifteen seconds forever to
+ * paint the same eight characters.
+ */
+function useDeadline(force: () => void, at: number | null, after: number): void {
+  React.useEffect(() => {
+    if (at === null) return;
+    const left = after - (Date.now() - at);
+    if (left <= 0) return;
+    const id = setTimeout(force, left);
+    return () => clearTimeout(id);
+  }, [force, at, after]);
+}
+
+function formatClock(at: number): string {
+  return new Date(at).toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit" });
+}
+
+function pauseNote(pausedBy: DataTableAutoRefreshState["pausedBy"]): string | null {
+  switch (pausedBy) {
+    case "hidden":
+      return "Paused while this tab is in the background";
+    case "editing":
+      return "Paused while a cell is being edited";
+    case "selection":
+      return "Paused while rows are selected";
+    case "mutation":
+      return "Paused while a change is saving";
+    case "app":
+      return "Paused";
+    default:
+      return null;
+  }
+}
+
+interface StampProps {
+  lastUpdatedAt: number | null;
+  lastErrorAt: number | null;
+}
+
+/**
+ * "Updated 14:32", or "Updated just now" for the first minute. A server table
+ * is a photograph of a moment, and this is the only thing on screen that says
+ * which moment. Its own component so a re-render at the minute boundary costs
+ * eight words rather than the whole toolbar.
+ */
+function DataTableUpdatedStamp({ lastUpdatedAt, lastErrorAt }: StampProps) {
+  const [, force] = React.useReducer((n: number) => n + 1, 0);
+  useDeadline(force, lastUpdatedAt, RELATIVE_WINDOW_MS);
+  useDeadline(force, lastErrorAt, ERROR_VISIBLE_MS);
+  const now = Date.now();
+
+  if (lastErrorAt !== null && now - lastErrorAt < ERROR_VISIBLE_MS) {
+    return (
+      <span
+        data-slot="data-table-updated"
+        data-failed=""
+        className="whitespace-nowrap text-[length:var(--ds-text-caption)] text-[color:var(--ds-destructive)]"
+      >
+        Update failed
+      </span>
+    );
+  }
+  if (lastUpdatedAt === null) return null;
+  return (
+    <span
+      data-slot="data-table-updated"
+      title={new Date(lastUpdatedAt).toLocaleString()}
+      className="whitespace-nowrap text-[length:var(--ds-text-caption)] text-[color:var(--ds-muted-foreground)]"
+    >
+      {now - lastUpdatedAt < RELATIVE_WINDOW_MS
+        ? "Updated just now"
+        : `Updated ${formatClock(lastUpdatedAt)}`}
+    </span>
+  );
+}
+
+export interface DataTableRefreshProps extends Omit<React.ComponentProps<"div">, "children"> {
+  /** Refetch the page on screen. The same query the interval drives. */
+  onRefresh: () => void;
+  /** Spins the icon and holds the button while a request is in flight. */
+  isFetching?: boolean;
+  /** `Date.now()` of the last successful response. */
+  lastUpdatedAt?: number | null;
+  /** `Date.now()` of the last failure; shown for ten seconds, then dropped. */
+  lastErrorAt?: number | null;
+  /** Renders the on/off switch and the live indicator. Omit for a table without `autoRefresh`. */
+  autoRefresh?: DataTableAutoRefreshState | null;
+}
+
+/**
+ * The freshness controls: Refresh, the last-updated stamp, and — only where a
+ * table opted in — the auto-refresh switch with its live indicator. Mandatory
+ * on every server-backed table (P-39); `DataTable` renders it beside the
+ * search box on its own.
+ */
+function DataTableRefresh({
+  onRefresh,
+  isFetching,
+  lastUpdatedAt = null,
+  lastErrorAt = null,
+  autoRefresh,
+  className,
+  ...props
+}: DataTableRefreshProps) {
+  const note = autoRefresh ? pauseNote(autoRefresh.pausedBy) : null;
+  return (
+    <div
+      data-slot="data-table-refresh"
+      className={cn("flex items-center gap-2", className)}
+      {...props}
+    >
+      <Button
+        variant="outline"
+        size="icon-sm"
+        aria-label="Refresh"
+        onClick={onRefresh}
+        disabled={isFetching}
+      >
+        <RefreshCw className={cn(isFetching && "animate-spin")} />
+      </Button>
+      <DataTableUpdatedStamp lastUpdatedAt={lastUpdatedAt} lastErrorAt={lastErrorAt} />
+      {autoRefresh ? (
+        <span data-slot="data-table-auto-refresh" className="flex items-center gap-1.5">
+          <Switch
+            aria-label="Auto refresh"
+            checked={autoRefresh.enabled}
+            onCheckedChange={autoRefresh.setEnabled}
+            data-backing-off={autoRefresh.backingOff ? "" : undefined}
+          />
+          {autoRefresh.active ? (
+            <StatusDot data-slot="data-table-live" tone="success" live label="Live" />
+          ) : (
+            <span
+              data-slot="data-table-auto-label"
+              title={note ?? undefined}
+              className="whitespace-nowrap text-[length:var(--ds-text-caption)] text-[color:var(--ds-muted-foreground)]"
+            >
+              {autoRefresh.enabled ? (note ? "Paused" : "Auto") : "Auto"}
+            </span>
+          )}
+        </span>
+      ) : null}
+    </div>
+  );
+}
+
 /* ------------------------------------------------------------------------ */
 /* Pagination                                                                */
 /* ------------------------------------------------------------------------ */
@@ -578,6 +753,7 @@ export {
   DataTableExportMenu,
   DataTableFacetedFilter,
   DataTablePagination,
+  DataTableRefresh,
   DataTableToolbar,
   DataTableViewOptions,
 };