@stigmer/react 0.0.36 → 0.0.40

package/src/internal/useScrollShadows.ts

@@ -0,0 +1,54 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export interface UseScrollShadowsReturn {
+  /** Attach to the scrollable container element. */
+  readonly scrollRef: React.RefObject<HTMLDivElement | null>;
+  /** `true` when the container has hidden content above the visible area. */
+  readonly canScrollUp: boolean;
+  /** `true` when the container has hidden content below the visible area. */
+  readonly canScrollDown: boolean;
+}
+
+/**
+ * Tracks whether a scrollable container can scroll up, down, or both.
+ *
+ * Attaches a passive `scroll` listener and a `ResizeObserver` to the
+ * referenced element so the returned booleans stay in sync with both
+ * user scrolling and content-size changes (e.g., new items appended).
+ *
+ * Pair with {@link ScrollFade} to render gradient overlays that signal
+ * hidden content above or below.
+ *
+ * @internal
+ */
+export function useScrollShadows(): UseScrollShadowsReturn {
+  const scrollRef = useRef<HTMLDivElement | null>(null);
+  const [canScrollUp, setCanScrollUp] = useState(false);
+  const [canScrollDown, setCanScrollDown] = useState(false);
+
+  const update = useCallback(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    setCanScrollUp(el.scrollTop > 0);
+    setCanScrollDown(el.scrollTop + el.clientHeight < el.scrollHeight - 1);
+  }, []);
+
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+
+    el.addEventListener("scroll", update, { passive: true });
+
+    const ro = new ResizeObserver(update);
+    ro.observe(el);
+
+    update();
+
+    return () => {
+      el.removeEventListener("scroll", update);
+      ro.disconnect();
+    };
+  }, [update]);
+
+  return { scrollRef, canScrollUp, canScrollDown };
+}

package/src/library/ResourceCountCard.tsx

@@ -0,0 +1,187 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+
+export interface ResourceCountCardProps {
+  /**
+   * Icon element rendered at the top of the card. Sized by the consumer.
+   *
+   * Should be marked `aria-hidden="true"` when purely decorative
+   * (typical for resource type icons alongside a text label).
+   */
+  readonly icon: React.ReactNode;
+  /** Display label — e.g. "Agents", "Skills", "MCP Servers". */
+  readonly label: string;
+  /**
+   * Resource count to display. When `undefined` and `isLoading` is
+   * true, a skeleton placeholder renders in its place. When `undefined`
+   * and `isLoading` is false, an em-dash is shown as a neutral
+   * placeholder.
+   *
+   * When a count is already available and `isLoading` becomes true
+   * again (refresh scenario), the existing count remains visible —
+   * no skeleton flash.
+   */
+  readonly count?: number;
+  /**
+   * Whether the count is being fetched. Shows a skeleton pulse when
+   * `count` is not yet available.
+   */
+  readonly isLoading?: boolean;
+  /**
+   * URL for the card. When provided, the card renders as an `<a>`
+   * element for accessible navigation (right-click, open in new tab,
+   * browser status bar URL preview).
+   *
+   * For SPA routing, combine with `onClick` and call `preventDefault`:
+   *
+   * ```tsx
+   * <ResourceCountCard
+   *   href="/library/agents"
+   *   onClick={(e) => { e.preventDefault(); router.push("/library/agents"); }}
+   *   // ...
+   * />
+   * ```
+   */
+  readonly href?: string;
+  /**
+   * Click handler. When `href` is also provided, the card renders as
+   * `<a>` — call `e.preventDefault()` for SPA navigation. When only
+   * `onClick` is provided without `href`, the card renders as
+   * `<button>`.
+   */
+  readonly onClick?: (e: React.MouseEvent) => void;
+  /** Additional CSS classes for the root element. */
+  readonly className?: string;
+}
+
+/**
+ * Card displaying a resource type icon, count, and label — designed
+ * for Library landing pages and resource dashboards.
+ *
+ * Purely presentational: the consumer provides the count (typically
+ * from {@link useAgentCount}, {@link useSkillCount}, or
+ * {@link useMcpServerCount}) and the card handles rendering, loading
+ * skeletons, and accessible navigation semantics.
+ *
+ * The root element adapts to the provided props:
+ *
+ * - `href` → `<a>` (link: right-click, open in new tab, Enter to follow)
+ * - `onClick` only → `<button>` (action: Enter/Space to activate)
+ * - Neither → `<div>` (static display)
+ *
+ * All visual properties flow through `--stgm-*` tokens.
+ *
+ * @example
+ * ```tsx
+ * // Static display
+ * const { count, isLoading } = useAgentCount("acme");
+ *
+ * <ResourceCountCard
+ *   icon={<BotIcon className="h-5 w-5" aria-hidden="true" />}
+ *   label="Agents"
+ *   count={count}
+ *   isLoading={isLoading}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Navigable card with SPA routing
+ * <ResourceCountCard
+ *   icon={<BotIcon className="h-5 w-5" aria-hidden="true" />}
+ *   label="Agents"
+ *   count={agentCount}
+ *   isLoading={isAgentLoading}
+ *   href="/library/agents"
+ *   onClick={(e) => {
+ *     e.preventDefault();
+ *     router.push("/library/agents");
+ *   }}
+ * />
+ * ```
+ *
+ * @see {@link useAgentCount} — data hook for agent count
+ * @see {@link useSkillCount} — data hook for skill count
+ * @see {@link useMcpServerCount} — data hook for MCP server count
+ */
+export function ResourceCountCard({
+  icon,
+  label,
+  count,
+  isLoading = false,
+  href,
+  onClick,
+  className,
+}: ResourceCountCardProps) {
+  const isInteractive = !!href || !!onClick;
+  const showSkeleton = isLoading && count === undefined;
+
+  const rootClasses = cn(
+    "flex flex-col rounded-lg border border-border bg-card p-4 text-left no-underline",
+    isInteractive && [
+      "cursor-pointer transition-colors hover:bg-accent/50",
+      "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+    ],
+    className,
+  );
+
+  const content = (
+    <>
+      <div className="text-muted-foreground">{icon}</div>
+      {showSkeleton ? (
+        <div
+          className="mt-3 h-7 w-12 animate-pulse rounded bg-muted"
+          aria-hidden="true"
+        />
+      ) : (
+        <div className="mt-3 text-2xl font-semibold tabular-nums text-foreground">
+          {count !== undefined ? count.toLocaleString() : "\u2014"}
+        </div>
+      )}
+      <div className="mt-1 text-sm text-muted-foreground">{label}</div>
+    </>
+  );
+
+  if (href) {
+    return (
+      <a
+        href={href}
+        onClick={onClick}
+        aria-label={buildAriaLabel(label, count, isLoading)}
+        className={rootClasses}
+      >
+        {content}
+      </a>
+    );
+  }
+
+  if (onClick) {
+    return (
+      <button
+        type="button"
+        onClick={onClick}
+        aria-label={buildAriaLabel(label, count, isLoading)}
+        className={rootClasses}
+      >
+        {content}
+      </button>
+    );
+  }
+
+  return <div className={rootClasses}>{content}</div>;
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+function buildAriaLabel(
+  label: string,
+  count: number | undefined,
+  isLoading: boolean,
+): string {
+  if (count !== undefined) return `${label}: ${count.toLocaleString()}`;
+  if (isLoading) return `${label}: loading`;
+  return label;
+}