@stigmer/react 0.0.99 → 0.0.101

package/src/internal/menu.tsx

@@ -0,0 +1,160 @@
+"use client";
+
+import * as React from "react";
+import { Menu as MenuPrimitive } from "@base-ui/react/menu";
+import { cn } from "@stigmer/theme";
+import { CheckIcon } from "lucide-react";
+
+// ---------------------------------------------------------------------------
+// SDK-internal styled Menu primitives over @base-ui/react.
+//
+// These are NOT exported from @stigmer/react. They provide a single source
+// of truth for dropdown menu styling across SDK styled components
+// (OrgSwitcher, UserMenu, etc.) so that every menu looks identical.
+//
+// Portaled content uses popover-* / main-area tokens per DD-005.
+// ---------------------------------------------------------------------------
+
+function Menu(props: MenuPrimitive.Root.Props) {
+  return <MenuPrimitive.Root {...props} />;
+}
+
+function MenuTrigger(props: MenuPrimitive.Trigger.Props) {
+  return <MenuPrimitive.Trigger {...props} />;
+}
+
+function MenuContent({
+  align = "start",
+  alignOffset = 0,
+  side = "bottom",
+  sideOffset = 4,
+  className,
+  ...props
+}: MenuPrimitive.Popup.Props &
+  Pick<
+    MenuPrimitive.Positioner.Props,
+    "align" | "alignOffset" | "side" | "sideOffset"
+  >) {
+  return (
+    <MenuPrimitive.Portal>
+      <MenuPrimitive.Positioner
+        className="isolate z-50 outline-none"
+        align={align}
+        alignOffset={alignOffset}
+        side={side}
+        sideOffset={sideOffset}
+      >
+        <MenuPrimitive.Popup
+          className={cn(
+            "bg-popover text-popover-foreground ring-foreground/10",
+            "data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
+            "data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95",
+            "data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+            "z-50 max-h-(--available-height) w-(--anchor-width) min-w-32 origin-(--transform-origin) overflow-x-hidden overflow-y-auto rounded-lg p-1 shadow-md ring-1 duration-100 outline-none data-closed:overflow-hidden",
+            className,
+          )}
+          {...props}
+        />
+      </MenuPrimitive.Positioner>
+    </MenuPrimitive.Portal>
+  );
+}
+
+function MenuItem({
+  className,
+  variant = "default",
+  ...props
+}: MenuPrimitive.Item.Props & {
+  variant?: "default" | "destructive";
+}) {
+  return (
+    <MenuPrimitive.Item
+      data-variant={variant}
+      className={cn(
+        "focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground",
+        "data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive-subtle data-[variant=destructive]:focus:text-destructive data-[variant=destructive]:*:[svg]:text-destructive",
+        "relative flex cursor-default items-center gap-1.5 rounded-md px-1.5 py-1 text-sm outline-hidden select-none",
+        "data-disabled:pointer-events-none data-disabled:opacity-50",
+        "[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function MenuRadioGroup(props: MenuPrimitive.RadioGroup.Props) {
+  return <MenuPrimitive.RadioGroup {...props} />;
+}
+
+function MenuRadioItem({
+  className,
+  children,
+  ...props
+}: MenuPrimitive.RadioItem.Props) {
+  return (
+    <MenuPrimitive.RadioItem
+      className={cn(
+        "focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground",
+        "relative flex cursor-default items-center gap-1.5 rounded-md py-1 pr-8 pl-1.5 text-sm outline-hidden select-none",
+        "data-disabled:pointer-events-none data-disabled:opacity-50",
+        "[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className,
+      )}
+      {...props}
+    >
+      <span className="pointer-events-none absolute right-2 flex items-center justify-center">
+        <MenuPrimitive.RadioItemIndicator>
+          <CheckIcon />
+        </MenuPrimitive.RadioItemIndicator>
+      </span>
+      {children}
+    </MenuPrimitive.RadioItem>
+  );
+}
+
+function MenuSeparator({
+  className,
+  ...props
+}: MenuPrimitive.Separator.Props) {
+  return (
+    <MenuPrimitive.Separator
+      className={cn("bg-border -mx-1 my-1 h-px", className)}
+      {...props}
+    />
+  );
+}
+
+function MenuGroup({
+  className,
+  ...props
+}: React.ComponentPropsWithoutRef<"div"> & { role?: string }) {
+  return <div role="group" className={className} {...props} />;
+}
+
+function MenuLabel({
+  className,
+  ...props
+}: React.ComponentPropsWithoutRef<"span">) {
+  return (
+    <span
+      className={cn(
+        "text-muted-foreground block px-1.5 py-1 text-[11px] font-medium uppercase tracking-wider select-none",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export {
+  Menu,
+  MenuTrigger,
+  MenuContent,
+  MenuItem,
+  MenuRadioGroup,
+  MenuRadioItem,
+  MenuSeparator,
+  MenuGroup,
+  MenuLabel,
+};

package/src/library/LibraryBreadcrumbContext.tsx

@@ -0,0 +1,70 @@
+"use client";
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+  type ReactNode,
+} from "react";
+
+interface BreadcrumbOverrideContextValue {
+  readonly label: string | null;
+  readonly setLabel: (label: string | null) => void;
+}
+
+const BreadcrumbOverrideContext =
+  createContext<BreadcrumbOverrideContextValue | null>(null);
+
+/**
+ * Provides a breadcrumb label override for library detail pages.
+ *
+ * Wrap the library zone in this provider so that detail pages can push
+ * a human-readable resource name into the breadcrumb via
+ * `useBreadcrumbOverride().setLabel(name)`.
+ */
+export function LibraryBreadcrumbProvider({
+  children,
+}: {
+  readonly children: ReactNode;
+}) {
+  const [label, setLabelState] = useState<string | null>(null);
+  const setLabel = useCallback(
+    (next: string | null) => setLabelState(next),
+    [],
+  );
+  const value = useMemo(() => ({ label, setLabel }), [label, setLabel]);
+
+  return (
+    <BreadcrumbOverrideContext.Provider value={value}>
+      {children}
+    </BreadcrumbOverrideContext.Provider>
+  );
+}
+
+/**
+ * Read the current breadcrumb override label.
+ *
+ * Used by breadcrumb UI components to display a resource display name
+ * instead of the raw URL slug for the last segment.
+ */
+export function useBreadcrumbLabel(): string | null {
+  return useContext(BreadcrumbOverrideContext)?.label ?? null;
+}
+
+/**
+ * Set (or clear) the breadcrumb override label.
+ *
+ * Used by detail pages to push the resource display name up to the
+ * breadcrumb after the resource data has loaded. Returns a stable
+ * `setLabel` function safe for use as a `useEffect` dependency.
+ */
+export function useBreadcrumbOverride(): {
+  /** Set or clear the breadcrumb label override for the active detail page. */
+  setLabel: (label: string | null) => void;
+} {
+  const ctx = useContext(BreadcrumbOverrideContext);
+  const noop = useCallback((_label: string | null) => {}, []);
+  return { setLabel: ctx?.setLabel ?? noop };
+}

package/src/library/index.ts

@@ -1,3 +1,9 @@
+export {
+  LibraryBreadcrumbProvider,
+  useBreadcrumbLabel,
+  useBreadcrumbOverride,
+} from "./LibraryBreadcrumbContext";
+
 export { ScopeToggle } from "./ScopeToggle";
 export type { ScopeToggleProps } from "./ScopeToggle";
 

package/src/organization/OrgProvider.tsx

@@ -0,0 +1,184 @@
+"use client";
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import type { Organization } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
+import { useStigmer } from "../hooks";
+
+/** Value exposed by {@link OrgProvider} via {@link useOrg}. */
+export interface OrgContextValue {
+  /** All organizations the authenticated user belongs to. */
+  readonly orgs: Organization[];
+  /** The currently selected organization. Null while loading or if the user has no orgs. */
+  readonly activeOrg: Organization | null;
+  /** Switch the active organization. Persisted to localStorage. */
+  readonly setActiveOrg: (org: Organization) => void;
+  /** True during the initial fetch of organizations. */
+  readonly isLoading: boolean;
+  /** Non-null when the fetch failed. */
+  readonly error: string | null;
+  /** Re-attempt the organization fetch after a failure. */
+  readonly retry: () => void;
+  /**
+   * Refetch the organization list. If `targetSlug` is provided, the
+   * org matching that slug will be auto-selected after the fetch
+   * completes (useful after creating a new organization).
+   */
+  readonly refresh: (targetSlug?: string) => void;
+}
+
+const OrgContext = createContext<OrgContextValue | null>(null);
+
+const STORAGE_KEY = "stigmer:activeOrgSlug";
+
+function readPersistedSlug(): string | null {
+  try {
+    return localStorage.getItem(STORAGE_KEY);
+  } catch {
+    return null;
+  }
+}
+
+function persistSlug(slug: string): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, slug);
+  } catch {
+    // SSR or private browsing — silently ignore.
+  }
+}
+
+/**
+ * Provides organization context to the component tree.
+ *
+ * Fetches the authenticated user's organizations via
+ * `stigmer.organization.findMyOrganizations()`, manages the active
+ * organization selection, and persists the choice to `localStorage`
+ * under the key `stigmer:activeOrgSlug`.
+ *
+ * Must be rendered inside a {@link StigmerProvider}.
+ *
+ * @example
+ * ```tsx
+ * <StigmerProvider client={client}>
+ *   <OrgProvider>
+ *     <App />
+ *   </OrgProvider>
+ * </StigmerProvider>
+ * ```
+ */
+export function OrgProvider({ children }: { children: ReactNode }) {
+  const stigmer = useStigmer();
+  const [orgs, setOrgs] = useState<Organization[]>([]);
+  const [activeOrg, setActiveOrgState] = useState<Organization | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const fetchIdRef = useRef(0);
+
+  const load = useCallback(
+    async (targetSlug?: string) => {
+      const fetchId = ++fetchIdRef.current;
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const response = await stigmer.organization.findMyOrganizations();
+        const entries = response.entries;
+
+        if (fetchId !== fetchIdRef.current) return;
+
+        setOrgs(entries);
+
+        if (entries.length === 0) {
+          setActiveOrgState(null);
+          return;
+        }
+
+        const preferred = targetSlug ?? readPersistedSlug();
+        const restored = preferred
+          ? entries.find((o) => o.metadata?.slug === preferred)
+          : undefined;
+
+        const selected = restored ?? entries[0];
+        setActiveOrgState(selected);
+        if (selected.metadata?.slug) {
+          persistSlug(selected.metadata.slug);
+        }
+      } catch (err: unknown) {
+        if (fetchId !== fetchIdRef.current) return;
+
+        const message =
+          err instanceof Error ? err.message : "Failed to load organizations";
+        setError(message);
+        setOrgs([]);
+        setActiveOrgState(null);
+      } finally {
+        if (fetchId === fetchIdRef.current) {
+          setIsLoading(false);
+        }
+      }
+    },
+    [stigmer],
+  );
+
+  useEffect(() => {
+    load();
+  }, [load]);
+
+  const setActiveOrg = useCallback((org: Organization) => {
+    setActiveOrgState(org);
+    if (org.metadata?.slug) {
+      persistSlug(org.metadata.slug);
+    }
+  }, []);
+
+  const value = useMemo<OrgContextValue>(
+    () => ({
+      orgs,
+      activeOrg,
+      setActiveOrg,
+      isLoading,
+      error,
+      retry: load,
+      refresh: load,
+    }),
+    [orgs, activeOrg, setActiveOrg, isLoading, error, load],
+  );
+
+  return <OrgContext.Provider value={value}>{children}</OrgContext.Provider>;
+}
+
+/**
+ * Access the active organization context from the nearest
+ * {@link OrgProvider}.
+ *
+ * Throws if called outside an `<OrgProvider>` — this surfaces wiring
+ * mistakes immediately during development.
+ */
+export function useOrg(): OrgContextValue {
+  const ctx = useContext(OrgContext);
+  if (!ctx) {
+    throw new Error(
+      "useOrg must be used within <OrgProvider>. " +
+        "Wrap your component tree with <OrgProvider> inside a <StigmerProvider>.",
+    );
+  }
+  return ctx;
+}
+
+/**
+ * Convenience accessor: returns the active org's slug for use in API
+ * calls, or an empty string when no org is selected.
+ */
+export function useActiveOrgSlug(): string {
+  const { activeOrg } = useOrg();
+  return activeOrg?.metadata?.slug ?? "";
+}

package/src/organization/OrgSwitcher.tsx

@@ -0,0 +1,275 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import {
+  Building2,
+  AlertCircle,
+  RefreshCw,
+  ChevronsUpDown,
+  Plus,
+  User,
+} from "lucide-react";
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import type { Organization } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
+import { cn } from "@stigmer/theme";
+import {
+  Menu,
+  MenuContent,
+  MenuItem,
+  MenuRadioGroup,
+  MenuRadioItem,
+  MenuSeparator,
+  MenuTrigger,
+} from "../internal/menu";
+import { useOrg } from "./OrgProvider";
+import { CreateOrganizationForm } from "./CreateOrganizationForm";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/** Props for {@link OrgSwitcher}. */
+export interface OrgSwitcherProps {
+  /**
+   * Called when the user explicitly switches to a different organization
+   * or creates a new one.
+   *
+   * This fires only on user-initiated changes — not on initial load,
+   * background refresh, or programmatic context updates. Use it to
+   * trigger side effects like navigation without fragile `useEffect`
+   * guards on the active org.
+   */
+  readonly onOrgChanged?: (org: Organization) => void;
+  /** Additional CSS class names merged onto the trigger (or root in error/loading states). */
+  readonly className?: string;
+}
+
+/**
+ * Organization switcher dropdown for sidebar navigation.
+ *
+ * Shows the active organization (name + slug), lists personal and team
+ * organizations grouped with icons, and provides a "Create organization"
+ * action that opens an inline dialog with {@link CreateOrganizationForm}.
+ *
+ * Designed for sidebar placement — the trigger uses `sidebar-*` design
+ * tokens. The portaled dropdown and dialog use standard `popover-*` /
+ * main-area tokens per theme-token-guidelines.
+ *
+ * Must be rendered inside an {@link OrgProvider}.
+ *
+ * @example
+ * ```tsx
+ * <OrgSwitcher onOrgChanged={(org) => navigate("/")} />
+ * ```
+ */
+export function OrgSwitcher({ onOrgChanged, className }: OrgSwitcherProps) {
+  const { orgs, activeOrg, setActiveOrg, isLoading, error, retry, refresh } =
+    useOrg();
+  const [createOpen, setCreateOpen] = useState(false);
+
+  const handleOrgSwitch = useCallback(
+    (slug: string) => {
+      const org = orgs.find((o) => o.metadata?.slug === slug);
+      if (org && org.metadata?.slug !== activeOrg?.metadata?.slug) {
+        setActiveOrg(org);
+        onOrgChanged?.(org);
+      }
+    },
+    [orgs, activeOrg, setActiveOrg, onOrgChanged],
+  );
+
+  const handleCreated = useCallback(
+    (org: Organization) => {
+      setCreateOpen(false);
+      refresh(org.metadata?.slug);
+      onOrgChanged?.(org);
+    },
+    [refresh, onOrgChanged],
+  );
+
+  const personalOrgs = useMemo(
+    () => orgs.filter((o) => o.spec?.isPersonal),
+    [orgs],
+  );
+  const teamOrgs = useMemo(
+    () => orgs.filter((o) => !o.spec?.isPersonal),
+    [orgs],
+  );
+
+  if (isLoading) {
+    return <OrgSwitcherSkeleton className={className} />;
+  }
+
+  if (error) {
+    return (
+      <div className={cn("flex items-center gap-2 px-2 py-1.5", className)}>
+        <AlertCircle className="text-destructive size-4 shrink-0" />
+        <span className="text-destructive truncate text-xs">{error}</span>
+        <button
+          onClick={retry}
+          className="text-sidebar-muted-foreground hover:text-sidebar-foreground shrink-0 rounded p-0.5 transition-colors"
+          aria-label="Retry loading organizations"
+        >
+          <RefreshCw className="size-3" />
+        </button>
+      </div>
+    );
+  }
+
+  const hasOrgs = orgs.length > 0 && activeOrg;
+  const TriggerIcon = activeOrg?.spec?.isPersonal ? User : Building2;
+
+  return (
+    <>
+      <Menu>
+        <MenuTrigger
+          aria-label="Organization menu"
+          className={cn(
+            "hover:bg-sidebar-accent flex w-full cursor-pointer items-center gap-2 rounded-lg px-2 py-1.5 text-sm transition-colors focus:outline-none",
+            className,
+          )}
+        >
+          <TriggerIcon className="text-sidebar-muted-foreground mt-0.5 size-4 shrink-0 self-start" />
+          {hasOrgs ? (
+            <OrgLabel
+              org={activeOrg}
+              slugClassName="text-sidebar-muted-foreground"
+            />
+          ) : (
+            <span className="text-sidebar-muted-foreground truncate">
+              No organizations
+            </span>
+          )}
+          <ChevronsUpDown className="text-sidebar-muted-foreground ml-auto mt-0.5 size-3.5 shrink-0 self-start" />
+        </MenuTrigger>
+
+        <MenuContent align="start" side="bottom" sideOffset={4}>
+          {hasOrgs && (
+            <MenuRadioGroup
+              value={activeOrg.metadata?.slug ?? ""}
+              onValueChange={handleOrgSwitch}
+            >
+              {personalOrgs.map((org) => (
+                <MenuRadioItem
+                  key={org.metadata?.slug}
+                  value={org.metadata?.slug ?? ""}
+                  className="items-start"
+                >
+                  <User className="mt-0.5 size-3.5 shrink-0" />
+                  <OrgLabel org={org} />
+                </MenuRadioItem>
+              ))}
+              {personalOrgs.length > 0 && teamOrgs.length > 0 && (
+                <MenuSeparator />
+              )}
+              {teamOrgs.map((org) => (
+                <MenuRadioItem
+                  key={org.metadata?.slug}
+                  value={org.metadata?.slug ?? ""}
+                  className="items-start"
+                >
+                  <Building2 className="mt-0.5 size-3.5 shrink-0" />
+                  <OrgLabel org={org} />
+                </MenuRadioItem>
+              ))}
+            </MenuRadioGroup>
+          )}
+
+          {hasOrgs && <MenuSeparator />}
+
+          <MenuItem onClick={() => setCreateOpen(true)}>
+            <Plus className="size-4" />
+            Create organization
+          </MenuItem>
+        </MenuContent>
+      </Menu>
+
+      <DialogPrimitive.Root
+        open={createOpen}
+        onOpenChange={(open) => setCreateOpen(open)}
+      >
+        <DialogPrimitive.Portal>
+          <DialogPrimitive.Backdrop
+            className={cn(
+              "fixed inset-0 z-50 bg-black/50",
+              "data-open:animate-in data-open:fade-in-0",
+              "data-closed:animate-out data-closed:fade-out-0",
+              "duration-150",
+            )}
+          />
+          {/* eslint-disable stigmer/no-main-tokens-in-sidebar -- The entire dialog is portaled outside the sidebar; main-area tokens are correct per DD-005. */}
+          <DialogPrimitive.Popup
+            className={cn(
+              "bg-background text-foreground ring-border/20",
+              "fixed top-1/2 left-1/2 z-50 w-full max-w-md -translate-x-1/2 -translate-y-1/2 rounded-lg p-6 shadow-lg ring-1 outline-none",
+              "data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95",
+              "data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+              "duration-150",
+            )}
+          >
+            <DialogPrimitive.Title className="text-foreground text-sm font-semibold">
+              Create organization
+            </DialogPrimitive.Title>
+            <DialogPrimitive.Description className="text-muted-foreground mt-1 mb-4 text-xs">
+              Organizations are tenancy boundaries that own agents,
+              environments, and other resources.
+            </DialogPrimitive.Description>
+            <CreateOrganizationForm
+              onCreated={handleCreated}
+              onCancel={() => setCreateOpen(false)}
+            />
+          </DialogPrimitive.Popup>
+          {/* eslint-enable stigmer/no-main-tokens-in-sidebar */}
+        </DialogPrimitive.Portal>
+      </DialogPrimitive.Root>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Internal sub-components
+// ---------------------------------------------------------------------------
+
+/**
+ * Two-line org label: name (bold) + slug (muted). Used in the trigger
+ * (sidebar context → pass `slugClassName="text-sidebar-muted-foreground"`)
+ * and in dropdown radio items (popover context → default `text-muted-foreground`).
+ */
+function OrgLabel({
+  org,
+  slugClassName,
+}: {
+  org: Organization;
+  slugClassName?: string;
+}) {
+  const name = org.metadata?.name || org.metadata?.slug;
+  const slug = org.metadata?.slug;
+
+  return (
+    <span className="min-w-0 flex-1">
+      <span className="block truncate text-sm font-medium leading-tight">
+        {name}
+      </span>
+      {slug && (
+        <span
+          className={cn(
+            "block truncate text-xs leading-tight",
+            // eslint-disable-next-line stigmer/no-main-tokens-in-sidebar -- OrgLabel renders inside portaled dropdown content (popover context)
+            slugClassName ?? "text-muted-foreground",
+          )}
+        >
+          {slug}
+        </span>
+      )}
+    </span>
+  );
+}
+
+function OrgSwitcherSkeleton({ className }: { className?: string }) {
+  return (
+    <div className={cn("flex items-center gap-2 px-2 py-1.5", className)}>
+      <div className="bg-sidebar-muted size-4 animate-pulse rounded" />
+      <div className="bg-sidebar-muted h-4 w-24 animate-pulse rounded" />
+    </div>
+  );
+}