@stigmer/react 0.0.36 → 0.0.40

package/src/skill/SkillPicker.tsx

@@ -0,0 +1,331 @@
+"use client";
+
+import {
+  useState,
+  useCallback,
+  useEffect,
+  useRef,
+  useMemo,
+  type KeyboardEvent,
+} from "react";
+import type { ResourceRef } from "@stigmer/sdk";
+import type { SearchResult } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { cn } from "@stigmer/theme";
+import { useSkillSearch } from "./useSkillSearch";
+import { useScrollShadows } from "../internal/useScrollShadows";
+import { ScrollFade } from "../internal/ScrollFade";
+
+export interface SkillPickerProps {
+  /** Organization slug to scope the search. */
+  readonly org: string;
+  /** Currently selected skill references. */
+  readonly value: ResourceRef[];
+  /** Called when the selection changes. */
+  readonly onChange: (refs: ResourceRef[]) => void;
+  /** Called with the display name when an item is added (for chip rendering). */
+  readonly onDisplayNameResolved?: (key: string, name: string) => void;
+  readonly disabled?: boolean;
+  readonly className?: string;
+}
+
+function refKey(ref: ResourceRef): string {
+  return `${ref.org}/${ref.slug}`;
+}
+
+const LIST_ID = "stgm-skill-list";
+
+/**
+ * Searchable picker for selecting skills from the platform.
+ *
+ * Renders a search input and scrollable list of available skills.
+ * Designed to be placed inside a popover container — this component
+ * renders the picker content, not the popover shell.
+ *
+ * Selected skills produce `ResourceRef[]` with `kind: skill`.
+ *
+ * All visual properties flow through `--stgm-*` tokens.
+ */
+export function SkillPicker({
+  org,
+  value,
+  onChange,
+  onDisplayNameResolved,
+  disabled,
+  className,
+}: SkillPickerProps) {
+  const { results, isLoading, error, query, setQuery } = useSkillSearch(org);
+
+  const [focusIndex, setFocusIndex] = useState(-1);
+  const searchRef = useRef<HTMLInputElement>(null);
+  const results_ = useScrollShadows();
+  const selected_ = useScrollShadows();
+
+  const selectedKeys = useMemo(
+    () => new Set(value.map(refKey)),
+    [value],
+  );
+
+  const availableResults = useMemo(
+    () => results.filter((r) => !selectedKeys.has(`${r.org}/${r.slug}`)),
+    [results, selectedKeys],
+  );
+
+  useEffect(() => {
+    setFocusIndex(-1);
+  }, [query]);
+
+  useEffect(() => {
+    if (focusIndex >= 0) {
+      results_.scrollRef.current
+        ?.querySelector(`[data-idx="${focusIndex}"]`)
+        ?.scrollIntoView({ block: "nearest" });
+    }
+  }, [focusIndex, results_.scrollRef]);
+
+  const handleSelect = useCallback(
+    (result: SearchResult) => {
+      const ref: ResourceRef = {
+        org: result.org,
+        slug: result.slug,
+        kind: ApiResourceKind.skill,
+      };
+      onChange([...value, ref]);
+      onDisplayNameResolved?.(`${result.org}/${result.slug}`, result.name);
+    },
+    [value, onChange, onDisplayNameResolved],
+  );
+
+  const handleRemove = useCallback(
+    (key: string) => {
+      onChange(value.filter((r) => refKey(r) !== key));
+    },
+    [value, onChange],
+  );
+
+  const handleSearchKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLInputElement>) => {
+      if (e.key === "ArrowDown") {
+        e.preventDefault();
+        setFocusIndex((prev) =>
+          prev < availableResults.length - 1 ? prev + 1 : prev,
+        );
+      } else if (e.key === "ArrowUp") {
+        e.preventDefault();
+        setFocusIndex((prev) => (prev > 0 ? prev - 1 : -1));
+      } else if (
+        e.key === "Enter" &&
+        focusIndex >= 0 &&
+        focusIndex < availableResults.length
+      ) {
+        e.preventDefault();
+        handleSelect(availableResults[focusIndex]);
+      } else if (e.key === "Enter") {
+        e.preventDefault();
+      }
+    },
+    [availableResults, focusIndex, handleSelect],
+  );
+
+  return (
+    <div className={["space-y-2 w-72", className].filter(Boolean).join(" ")}>
+      {/* Selected items */}
+      {value.length > 0 && (
+        <div className="space-y-1">
+          <div className="text-[0.65rem] font-medium text-muted-foreground">
+            Selected
+          </div>
+          <div className="relative">
+            {selected_.canScrollUp && <ScrollFade position="top" />}
+
+            <div ref={selected_.scrollRef} className="max-h-28 space-y-1 overflow-y-auto">
+              {value.map((ref) => {
+                const key = refKey(ref);
+                return (
+                  <div
+                    key={key}
+                    className="flex items-center gap-2 rounded-md bg-muted/30 px-2 py-1 text-xs"
+                  >
+                    <SkillIcon />
+                    <span className="min-w-0 flex-1 truncate text-foreground">
+                      {ref.slug}
+                    </span>
+                    <button
+                      type="button"
+                      onClick={() => handleRemove(key)}
+                      disabled={disabled}
+                      className="shrink-0 text-muted-foreground hover:text-destructive disabled:pointer-events-none"
+                      aria-label={`Remove ${ref.slug}`}
+                    >
+                      <XIcon />
+                    </button>
+                  </div>
+                );
+              })}
+            </div>
+
+            {selected_.canScrollDown && <ScrollFade position="bottom" />}
+          </div>
+        </div>
+      )}
+
+      {/* Search input */}
+      <input
+        ref={searchRef}
+        type="text"
+        role="combobox"
+        aria-expanded={true}
+        aria-controls={LIST_ID}
+        aria-activedescendant={
+          focusIndex >= 0 ? `stgm-skill-${focusIndex}` : undefined
+        }
+        placeholder="Search skills..."
+        value={query}
+        onChange={(e) => setQuery(e.target.value)}
+        onKeyDown={handleSearchKeyDown}
+        disabled={disabled}
+        className="w-full rounded-md border border-input bg-background px-2.5 py-1.5 text-xs text-foreground placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50"
+        autoFocus
+      />
+
+      {error && <p className="text-xs text-destructive">{error}</p>}
+
+      {/* Scrollable results list */}
+      <div className="relative">
+        {results_.canScrollUp && <ScrollFade position="top" />}
+
+        <div
+          ref={results_.scrollRef}
+          id={LIST_ID}
+          role="listbox"
+          aria-label="Skills"
+          className="max-h-52 overflow-y-auto"
+        >
+          {isLoading ? (
+            <LoadingSkeleton />
+          ) : availableResults.length === 0 ? (
+            <div className="py-4 text-center text-xs text-muted-foreground">
+              {query
+                ? "No skills match your search"
+                : value.length > 0
+                  ? "All available skills selected"
+                  : "No skills found"}
+            </div>
+          ) : (
+            availableResults.map((result, idx) => (
+              <button
+                key={result.id}
+                id={`stgm-skill-${idx}`}
+                type="button"
+                data-idx={idx}
+                onClick={() => handleSelect(result)}
+                disabled={disabled}
+                className={cn(
+                  "group flex w-full flex-col gap-0.5 rounded-md px-2 py-1.5 text-left text-xs transition-colors",
+                  "disabled:pointer-events-none disabled:opacity-50",
+                  idx === focusIndex
+                    ? "bg-accent text-foreground"
+                    : "text-foreground hover:bg-accent/50",
+                )}
+                role="option"
+                aria-selected={idx === focusIndex}
+              >
+                <span className="flex items-center gap-1.5">
+                  <SkillIcon />
+                  <span className="truncate font-medium">
+                    <HighlightMatch text={result.name} query={query} />
+                  </span>
+                  <span className="ml-auto shrink-0 text-[0.6rem] text-muted-foreground">
+                    {result.org}
+                  </span>
+                </span>
+                {result.description && (
+                  <span
+                    className={cn(
+                      "pl-5 text-[0.65rem] text-muted-foreground",
+                      idx !== focusIndex &&
+                        "line-clamp-2 group-hover:line-clamp-none",
+                    )}
+                  >
+                    {result.description}
+                  </span>
+                )}
+              </button>
+            ))
+          )}
+        </div>
+
+        {results_.canScrollDown && <ScrollFade position="bottom" />}
+      </div>
+    </div>
+  );
+}
+
+function HighlightMatch({ text, query }: { text: string; query: string }) {
+  if (!query) return <>{text}</>;
+  const idx = text.toLowerCase().indexOf(query.toLowerCase());
+  if (idx === -1) return <>{text}</>;
+  return (
+    <>
+      {text.slice(0, idx)}
+      <span className="font-semibold">{text.slice(idx, idx + query.length)}</span>
+      {text.slice(idx + query.length)}
+    </>
+  );
+}
+
+function LoadingSkeleton() {
+  return (
+    <div className="space-y-1 py-1">
+      {[55, 70, 45, 62].map((w, i) => (
+        <div key={i} className="flex flex-col gap-1 px-2 py-1.5">
+          <div
+            className="h-3 rounded bg-muted animate-pulse"
+            style={{ width: `${w}%` }}
+          />
+          <div
+            className="h-2 rounded bg-muted/60 animate-pulse"
+            style={{ width: `${Math.min(w + 15, 90)}%` }}
+          />
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function SkillIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="shrink-0 text-muted-foreground"
+      aria-hidden="true"
+    >
+      <path d="M2 3h12M2 7h8M2 11h10M2 15h6" />
+    </svg>
+  );
+}
+
+function XIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 14 14"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M4 4L10 10M10 4L4 10" />
+    </svg>
+  );
+}

package/src/skill/index.ts

@@ -1,6 +1,26 @@
-// Hooks
-export { useSkillSearch } from "./hooks/useSkillSearch";
+export { useSkillList } from "./useSkillList";
+export type {
+  UseSkillListOptions,
+  UseSkillListReturn,
+} from "./useSkillList";
+
+export { useSkillCount } from "./useSkillCount";
+export type {
+  UseSkillCountOptions,
+  UseSkillCountReturn,
+} from "./useSkillCount";
+
+export { useSkillSearch } from "./useSkillSearch";
 export type {
   UseSkillSearchOptions,
   UseSkillSearchReturn,
-} from "./hooks/useSkillSearch";
+} from "./useSkillSearch";
+
+export { useSkill } from "./useSkill";
+export type { UseSkillReturn } from "./useSkill";
+
+export { SkillPicker } from "./SkillPicker";
+export type { SkillPickerProps } from "./SkillPicker";
+
+export { SkillDetailView } from "./SkillDetailView";
+export type { SkillDetailViewProps } from "./SkillDetailView";

package/src/skill/useSkill.ts

@@ -0,0 +1,105 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import { isNotFound } from "@stigmer/sdk";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+export interface UseSkillReturn {
+  /** The resolved skill, or `null` while loading, on error, or when not found. */
+  readonly skill: Skill | null;
+  readonly isLoading: boolean;
+  readonly error: Error | null;
+  /** Re-fetch the skill with the same parameters. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches a single Skill by organization, slug, and
+ * optional version.
+ *
+ * Wraps `stigmer.skill.getByReference()` with loading, error, and
+ * not-found state management. When `org`, `slug`, or `version` change,
+ * the previous in-flight request is discarded and a fresh fetch begins.
+ *
+ * Pass `null` for either `org` or `slug` to skip fetching (stable
+ * no-op). The `version` parameter is optional — omit it to fetch the
+ * latest version. Pass a tag (e.g. `"stable"`) or a content hash to
+ * pin to a specific version.
+ *
+ * **Not-found handling:** If the API returns a 404 (NOT_FOUND), the
+ * hook sets `skill` to `null` without raising an error. Consumers
+ * distinguish "not found" from "loading" by checking all three fields:
+ * `skill === null && !isLoading && !error` means the resource does
+ * not exist.
+ *
+ * @example
+ * ```tsx
+ * function SkillDetail({ org, slug }: { org: string; slug: string }) {
+ *   const { skill, isLoading, error } = useSkill(org, slug);
+ *
+ *   if (isLoading) return <Skeleton />;
+ *   if (error) return <ErrorMessage error={error} />;
+ *   if (!skill) return <NotFound />;
+ *
+ *   return <h1>{skill.metadata?.name}</h1>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Fetch a specific tagged version
+ * const { skill } = useSkill("acme", "code-style-guide", "stable");
+ * ```
+ */
+export function useSkill(
+  org: string | null,
+  slug: string | null,
+  version?: string,
+): UseSkillReturn {
+  const stigmer = useStigmer();
+  const [skill, setSkill] = useState<Skill | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [fetchKey, setFetchKey] = useState(0);
+
+  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+
+  useEffect(() => {
+    if (!org || !slug) {
+      setSkill(null);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    const cancelled = { current: false };
+    setIsLoading(true);
+    setError(null);
+
+    stigmer.skill.getByReference({ org, slug, version }).then(
+      (result) => {
+        if (cancelled.current) return;
+        setSkill(result);
+        setIsLoading(false);
+      },
+      (err) => {
+        if (cancelled.current) return;
+        if (isNotFound(err)) {
+          setSkill(null);
+          setIsLoading(false);
+          return;
+        }
+        setError(toError(err));
+        setIsLoading(false);
+      },
+    );
+
+    return () => {
+      cancelled.current = true;
+    };
+  }, [org, slug, version, stigmer, fetchKey]);
+
+  return { skill, isLoading, error, refetch };
+}

package/src/skill/useSkillCount.ts

@@ -0,0 +1,68 @@
+"use client";
+
+import { useCallback } from "react";
+import { useStigmer } from "../hooks";
+import { useResourceCount, type ResourceListScope } from "../search";
+
+export interface UseSkillCountOptions {
+  /** Text query to filter skills before counting. */
+  readonly query?: string;
+  /**
+   * Controls which skills are counted.
+   *
+   * - `"org"` — only skills owned by the given organization.
+   * - `"all"` — includes public/platform skills.
+   *
+   * @default "org"
+   */
+  readonly scope?: ResourceListScope;
+}
+
+export interface UseSkillCountReturn {
+  /**
+   * Total number of skills matching the current filters. `undefined`
+   * until the first successful fetch completes.
+   */
+  readonly count: number | undefined;
+  readonly isLoading: boolean;
+  readonly error: string | null;
+  /** Re-fetch the count with the same parameters. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches the total count of skills.
+ *
+ * Issues a minimal `stigmer.skill.list()` call to retrieve only the
+ * total count — no skill entries are returned or stored. Useful for
+ * summary cards, badges, and dashboard widgets.
+ *
+ * For the full paginated skill list, use {@link useSkillList} instead.
+ *
+ * Pass `null` as `org` to skip fetching (stable no-op).
+ *
+ * @example
+ * ```tsx
+ * const { count, isLoading } = useSkillCount("acme");
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Count all accessible skills including public/platform ones
+ * const { count } = useSkillCount("acme", { scope: "all" });
+ * ```
+ */
+export function useSkillCount(
+  org: string | null,
+  options?: UseSkillCountOptions,
+): UseSkillCountReturn {
+  const stigmer = useStigmer();
+
+  const listFn = useCallback(
+    (params: Parameters<typeof stigmer.skill.list>[0]) =>
+      stigmer.skill.list(params),
+    [stigmer],
+  );
+
+  return useResourceCount(listFn, org, options);
+}

package/src/skill/useSkillList.ts

@@ -0,0 +1,84 @@
+"use client";
+
+import { useCallback } from "react";
+import type { SearchResult } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { useResourceList, type ResourceListScope } from "../search";
+
+export interface UseSkillListOptions {
+  /** Maximum skills per page. @default 20 */
+  readonly pageSize?: number;
+  /** Page number (1-indexed). @default 1 */
+  readonly page?: number;
+  /** Text query to filter skills by name, description, or tags. */
+  readonly query?: string;
+  /**
+   * Controls which skills are visible.
+   *
+   * - `"org"` — only skills owned by the given organization.
+   * - `"all"` — includes public/platform skills.
+   *
+   * @default "org"
+   */
+  readonly scope?: ResourceListScope;
+}
+
+export interface UseSkillListReturn {
+  /** Paginated skill entries for the current page. */
+  readonly skills: readonly SearchResult[];
+  /** Total number of skills matching the current filters. */
+  readonly totalCount: number;
+  /** Total pages available at the current page size. */
+  readonly totalPages: number;
+  /** The current page number (mirrors the `page` option). */
+  readonly currentPage: number;
+  readonly isLoading: boolean;
+  readonly error: string | null;
+  /** Re-fetch the current page with the same parameters. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches a paginated list of skills for the Library.
+ *
+ * Wraps `stigmer.skill.list()` with pagination, scope filtering,
+ * and text search. All parameters are externally controlled — the
+ * consumer manages page state, query debouncing, and scope toggling.
+ *
+ * For picker/type-ahead search with internal debouncing and query
+ * state management, use {@link useSkillSearch} instead.
+ *
+ * Pass `null` as `org` to skip fetching (stable no-op).
+ *
+ * @example
+ * ```tsx
+ * const { skills, totalCount, isLoading } = useSkillList("acme", {
+ *   page: 1,
+ *   pageSize: 20,
+ *   scope: "org",
+ * });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Show all skills including public/platform ones
+ * const { skills } = useSkillList("acme", { scope: "all" });
+ * ```
+ */
+export function useSkillList(
+  org: string | null,
+  options?: UseSkillListOptions,
+): UseSkillListReturn {
+  const stigmer = useStigmer();
+
+  const listFn = useCallback(
+    (params: Parameters<typeof stigmer.skill.list>[0]) =>
+      stigmer.skill.list(params),
+    [stigmer],
+  );
+
+  const { entries, totalCount, totalPages, currentPage, isLoading, error, refetch } =
+    useResourceList(listFn, org, options);
+
+  return { skills: entries, totalCount, totalPages, currentPage, isLoading, error, refetch };
+}

package/src/skill/useSkillSearch.ts

@@ -0,0 +1,38 @@
+"use client";
+
+import { useCallback } from "react";
+import { useStigmer } from "../hooks";
+import {
+  useResourceSearch,
+  type UseResourceSearchOptions,
+  type UseResourceSearchReturn,
+} from "../search";
+
+export type UseSkillSearchOptions = UseResourceSearchOptions;
+export type UseSkillSearchReturn = UseResourceSearchReturn;
+
+/**
+ * Data hook that searches skills available in the given organization.
+ *
+ * Wraps `stigmer.skill.list()` with debounced search, loading/error
+ * tracking, and cancellation-safe fetching. Platform builders use this
+ * when they want full control over rendering; the {@link SkillPicker}
+ * styled component uses it internally.
+ *
+ * @example
+ * ```tsx
+ * const { results, isLoading, query, setQuery } = useSkillSearch("acme");
+ * ```
+ */
+export function useSkillSearch(
+  org: string,
+  options?: UseSkillSearchOptions,
+): UseSkillSearchReturn {
+  const stigmer = useStigmer();
+  const listFn = useCallback(
+    (params: Parameters<typeof stigmer.skill.list>[0]) =>
+      stigmer.skill.list(params),
+    [stigmer],
+  );
+  return useResourceSearch(listFn, org, options);
+}

package/src/styles.css

@@ -1,3 +1,5 @@
+@source "./**/*.{ts,tsx}";
+
 @layer stgm;
 
 @import "tailwindcss/theme.css" layer(stgm);