@agent-native/toolkit 0.0.0-beta-20260819143124

package/src/hooks/use-toast.ts

@@ -0,0 +1,188 @@
+import * as React from "react";
+
+import type { ToastActionElement, ToastProps } from "../ui/toast.js";
+
+const TOAST_LIMIT = 1;
+const TOAST_REMOVE_DELAY = 1000000;
+
+type ToasterToast = ToastProps & {
+  id: string;
+  title?: React.ReactNode;
+  description?: React.ReactNode;
+  action?: ToastActionElement;
+};
+
+const actionTypes = {
+  ADD_TOAST: "ADD_TOAST",
+  UPDATE_TOAST: "UPDATE_TOAST",
+  DISMISS_TOAST: "DISMISS_TOAST",
+  REMOVE_TOAST: "REMOVE_TOAST",
+} as const;
+
+let count = 0;
+
+function genId() {
+  count = (count + 1) % Number.MAX_SAFE_INTEGER;
+  return count.toString();
+}
+
+type ActionType = typeof actionTypes;
+
+type Action =
+  | {
+      type: ActionType["ADD_TOAST"];
+      toast: ToasterToast;
+    }
+  | {
+      type: ActionType["UPDATE_TOAST"];
+      toast: Partial<ToasterToast>;
+    }
+  | {
+      type: ActionType["DISMISS_TOAST"];
+      toastId?: ToasterToast["id"];
+    }
+  | {
+      type: ActionType["REMOVE_TOAST"];
+      toastId?: ToasterToast["id"];
+    };
+
+interface State {
+  toasts: ToasterToast[];
+}
+
+const toastTimeouts = new Map<string, ReturnType<typeof setTimeout>>();
+
+const addToRemoveQueue = (toastId: string) => {
+  if (toastTimeouts.has(toastId)) {
+    return;
+  }
+
+  const timeout = setTimeout(() => {
+    toastTimeouts.delete(toastId);
+    dispatch({
+      type: "REMOVE_TOAST",
+      toastId: toastId,
+    });
+  }, TOAST_REMOVE_DELAY);
+
+  toastTimeouts.set(toastId, timeout);
+};
+
+export const reducer = (state: State, action: Action): State => {
+  switch (action.type) {
+    case "ADD_TOAST":
+      return {
+        ...state,
+        toasts: [action.toast, ...state.toasts].slice(0, TOAST_LIMIT),
+      };
+
+    case "UPDATE_TOAST":
+      return {
+        ...state,
+        toasts: state.toasts.map((t) =>
+          t.id === action.toast.id ? { ...t, ...action.toast } : t,
+        ),
+      };
+
+    case "DISMISS_TOAST": {
+      const { toastId } = action;
+
+      // ! Side effects ! - This could be extracted into a dismissToast() action,
+      // but I'll keep it here for simplicity
+      if (toastId) {
+        addToRemoveQueue(toastId);
+      } else {
+        state.toasts.forEach((toast) => {
+          addToRemoveQueue(toast.id);
+        });
+      }
+
+      return {
+        ...state,
+        toasts: state.toasts.map((t) =>
+          t.id === toastId || toastId === undefined
+            ? {
+                ...t,
+                open: false,
+              }
+            : t,
+        ),
+      };
+    }
+    case "REMOVE_TOAST":
+      if (action.toastId === undefined) {
+        return {
+          ...state,
+          toasts: [],
+        };
+      }
+      return {
+        ...state,
+        toasts: state.toasts.filter((t) => t.id !== action.toastId),
+      };
+  }
+};
+
+const listeners: Array<(state: State) => void> = [];
+
+let memoryState: State = { toasts: [] };
+
+function dispatch(action: Action) {
+  memoryState = reducer(memoryState, action);
+  listeners.forEach((listener) => {
+    listener(memoryState);
+  });
+}
+
+type Toast = Omit<ToasterToast, "id">;
+
+function toast({ ...props }: Toast) {
+  const id = genId();
+
+  const update = (props: ToasterToast) =>
+    dispatch({
+      type: "UPDATE_TOAST",
+      toast: { ...props, id },
+    });
+  const dismiss = () => dispatch({ type: "DISMISS_TOAST", toastId: id });
+
+  dispatch({
+    type: "ADD_TOAST",
+    toast: {
+      ...props,
+      id,
+      open: true,
+      onOpenChange: (open: boolean) => {
+        if (!open) dismiss();
+      },
+    },
+  });
+
+  return {
+    id: id,
+    dismiss,
+    update,
+  };
+}
+
+function useToast() {
+  const [state, setState] = React.useState<State>(memoryState);
+
+  React.useEffect(() => {
+    listeners.push(setState);
+    return () => {
+      const index = listeners.indexOf(setState);
+      if (index > -1) {
+        listeners.splice(index, 1);
+      }
+    };
+  }, [state]);
+
+  return {
+    ...state,
+    toast,
+    dismiss: (toastId?: string) => dispatch({ type: "DISMISS_TOAST", toastId }),
+  };
+}
+
+export { useToast, toast };

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from "./app-shell/index.js";
+export * from "./canvas-interactions/index.js";
+export * from "./collab-ui/index.js";
+export * from "./dashboard/index.js";
+export * from "./hooks/index.js";
+export * from "./onboarding/index.js";
+export * from "./provider.js";
+export * from "./sharing/index.js";
+export * from "./ui/index.js";
+export * from "./utils.js";

package/src/onboarding/index.ts

@@ -0,0 +1 @@
+export {};

package/src/provider.tsx

@@ -0,0 +1,148 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  type ElementType,
+  type ReactNode,
+  type ComponentType,
+} from "react";
+
+import {
+  DesignSystemContext,
+  LegacyButtonRenderContext,
+  type DesignSystemContextValue,
+} from "./design-system/context.js";
+import type { DesignSystemDefinition } from "./design-system/definition.js";
+import type {
+  ActionButtonProps,
+  DesignSystemComponents,
+} from "./design-system/types.js";
+import type { ButtonProps } from "./ui/button.js";
+
+export interface ToolkitComponents {
+  Button?: ComponentType<ButtonProps>;
+}
+
+export interface ToolkitProviderProps {
+  children: ReactNode;
+  components?: ToolkitComponents;
+  designSystem?: DesignSystemDefinition;
+}
+
+const ToolkitComponentsContext = createContext<ToolkitComponents>({});
+
+export function ToolkitProvider({
+  children,
+  components,
+  designSystem,
+}: ToolkitProviderProps) {
+  const parent = useContext(ToolkitComponentsContext);
+  const parentDesignSystem = useContext(DesignSystemContext);
+  const value = useMemo<ToolkitComponents>(
+    () => ({ ...parent, ...components }),
+    [parent, components],
+  );
+  const mergedDefinition = useMemo<DesignSystemDefinition | undefined>(() => {
+    if (!designSystem) return parentDesignSystem.definition;
+    return {
+      ...parentDesignSystem.definition,
+      ...designSystem,
+      components: {
+        ...parentDesignSystem.definition?.components,
+        ...designSystem.components,
+      },
+    };
+  }, [designSystem, parentDesignSystem.definition]);
+  const legacyActionButton = useMemo<
+    DesignSystemComponents["ActionButton"] | undefined
+  >(() => {
+    if (!value.Button) return parentDesignSystem.legacyActionButton;
+    const LegacyButton = value.Button as ElementType<
+      ButtonProps & { ref?: ActionButtonProps["elementRef"] }
+    >;
+    return function LegacyActionButton({
+      children,
+      intent,
+      emphasis,
+      size,
+      pending,
+      leadingIcon,
+      trailingIcon,
+      onPress,
+      onClick,
+      elementRef,
+      ...props
+    }: ActionButtonProps) {
+      const variant =
+        emphasis === "ghost"
+          ? "ghost"
+          : emphasis === "outline"
+            ? "outline"
+            : intent === "danger"
+              ? "destructive"
+              : intent === "primary"
+                ? "default"
+                : "secondary";
+      const legacySize =
+        size === "compact" ? "sm" : size === "large" ? "lg" : "default";
+      return (
+        <LegacyButtonRenderContext.Provider value={true}>
+          <LegacyButton
+            {...props}
+            ref={elementRef}
+            variant={variant}
+            size={legacySize}
+            disabled={props.disabled || pending}
+            aria-busy={pending || undefined}
+            onClick={(event) => {
+              onPress?.(event);
+              onClick?.(
+                event as Parameters<
+                  NonNullable<ActionButtonProps["onClick"]>
+                >[0],
+              );
+            }}
+          >
+            {leadingIcon}
+            {children}
+            {trailingIcon}
+          </LegacyButton>
+        </LegacyButtonRenderContext.Provider>
+      );
+    };
+  }, [parentDesignSystem.legacyActionButton, value.Button]);
+  const designSystemValue = useMemo<DesignSystemContextValue>(
+    () => ({ definition: mergedDefinition, legacyActionButton }),
+    [legacyActionButton, mergedDefinition],
+  );
+
+  useEffect(() => {
+    if (!mergedDefinition?.components?.ActionButton || !value.Button) return;
+    const isDevelopment =
+      (import.meta as ImportMeta & { env?: { DEV?: boolean } }).env?.DEV ??
+      true;
+    if (!isDevelopment) return;
+    console.warn(
+      "[agent-native] ToolkitProvider received both designSystem.components.ActionButton and legacy components.Button. ActionButton takes precedence.",
+    );
+  }, [mergedDefinition?.components?.ActionButton, value.Button]);
+
+  return (
+    <DesignSystemContext.Provider value={designSystemValue}>
+      <ToolkitComponentsContext.Provider value={value}>
+        {children}
+      </ToolkitComponentsContext.Provider>
+    </DesignSystemContext.Provider>
+  );
+}
+
+export function useToolkitComponents(): ToolkitComponents {
+  return useContext(ToolkitComponentsContext);
+}
+
+export function useToolkitComponent<Name extends keyof ToolkitComponents>(
+  name: Name,
+): ToolkitComponents[Name] {
+  return useToolkitComponents()[name];
+}

package/src/sharing/SharePrimitives.tsx

@@ -0,0 +1,224 @@
+import { IconChevronDown } from "@tabler/icons-react";
+import { forwardRef, useEffect, useRef, useState, type ReactNode } from "react";
+
+import { ActionButton } from "../design-system/components.js";
+import type { ActionButtonProps } from "../design-system/types.js";
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "../ui/collapsible.js";
+import { cn } from "../utils.js";
+
+export interface ShareTriggerProps extends Pick<
+  ActionButtonProps,
+  | "aria-label"
+  | "aria-expanded"
+  | "aria-controls"
+  | "className"
+  | "disabled"
+  | "emphasis"
+  | "intent"
+  | "onClick"
+  | "onPress"
+  | "pending"
+  | "size"
+  | "title"
+> {
+  label?: ReactNode;
+}
+
+/** The shared text-only trigger for resource sharing surfaces. */
+export const ShareTrigger = forwardRef<HTMLButtonElement, ShareTriggerProps>(
+  function ShareTrigger(
+    { label = "Share", "aria-label": ariaLabel, title, ...props },
+    ref,
+  ) {
+    return (
+      <ActionButton
+        type="button"
+        emphasis="outline"
+        size="compact"
+        elementRef={ref}
+        aria-label={ariaLabel ?? (typeof label === "string" ? label : "Share")}
+        title={title ?? (typeof label === "string" ? label : undefined)}
+        {...props}
+      >
+        {label}
+      </ActionButton>
+    );
+  },
+);
+ShareTrigger.displayName = "ShareTrigger";
+
+export interface ShareCopyRowProps {
+  value: string;
+  label?: ReactNode;
+  description?: ReactNode;
+  disabled?: boolean;
+  className?: string;
+  copyLabel?: ReactNode;
+  copiedLabel?: ReactNode;
+  onCopy: (value: string) => Promise<boolean | void> | boolean | void;
+}
+
+/** Compact copy-only row. The underlying URL is deliberately not rendered. */
+export function ShareCopyRow({
+  value,
+  label,
+  description,
+  disabled = false,
+  className,
+  copyLabel = "Copy",
+  copiedLabel = "Copied",
+  onCopy,
+}: ShareCopyRowProps) {
+  const [copied, setCopied] = useState(false);
+  const resetTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(
+    () => () => {
+      if (resetTimer.current) clearTimeout(resetTimer.current);
+    },
+    [],
+  );
+
+  const handleCopy = async () => {
+    if (disabled) return;
+    const result = await onCopy(value);
+    if (result === false) return;
+    setCopied(true);
+    if (resetTimer.current) clearTimeout(resetTimer.current);
+    resetTimer.current = setTimeout(() => setCopied(false), 1_400);
+  };
+
+  return (
+    <div className={cn("flex items-center justify-between gap-3", className)}>
+      <div className="min-w-0">
+        {label ? <div className="text-sm font-medium">{label}</div> : null}
+        {description ? (
+          <div className="text-xs text-muted-foreground">{description}</div>
+        ) : null}
+      </div>
+      <ActionButton
+        type="button"
+        emphasis="outline"
+        size="compact"
+        disabled={disabled}
+        aria-label={copied ? String(copiedLabel) : String(copyLabel)}
+        onPress={() => void handleCopy()}
+        className="h-9 shrink-0"
+      >
+        {copied ? copiedLabel : copyLabel}
+      </ActionButton>
+    </div>
+  );
+}
+
+export interface ShareDisclosureSectionProps {
+  children: ReactNode;
+  label: ReactNode;
+  fallbackLabel?: string;
+  defaultOpen?: boolean;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  className?: string;
+  contentClassName?: string;
+}
+
+/** Shared expandable boundary for optional share-access details. */
+export function ShareDisclosureSection({
+  children,
+  label,
+  fallbackLabel = "Share details",
+  defaultOpen = false,
+  open,
+  onOpenChange,
+  className,
+  contentClassName,
+}: ShareDisclosureSectionProps) {
+  const [internalOpen, setInternalOpen] = useState(defaultOpen);
+  const isOpen = open ?? internalOpen;
+  const accessibleLabel = typeof label === "string" ? label : fallbackLabel;
+  const handleOpenChange = (nextOpen: boolean) => {
+    if (open === undefined) setInternalOpen(nextOpen);
+    onOpenChange?.(nextOpen);
+  };
+
+  return (
+    <Collapsible
+      open={isOpen}
+      onOpenChange={handleOpenChange}
+      className={cn(
+        "overflow-hidden rounded-md border border-border",
+        className,
+      )}
+    >
+      <CollapsibleTrigger asChild>
+        <ShareTrigger
+          label={
+            <>
+              <span className="min-w-0 truncate">{label}</span>
+              <IconChevronDown
+                aria-hidden="true"
+                className={cn(
+                  "size-4 shrink-0 text-muted-foreground transition-transform",
+                  isOpen && "rotate-180",
+                )}
+              />
+            </>
+          }
+          emphasis="ghost"
+          size="default"
+          aria-label={accessibleLabel}
+          title={accessibleLabel}
+          aria-expanded={isOpen}
+          className="flex min-h-10 w-full items-center justify-between gap-3 px-3 py-2 text-left text-sm font-medium hover:bg-muted/50 focus-visible:ring-inset"
+        />
+      </CollapsibleTrigger>
+      <CollapsibleContent
+        className={cn("border-t border-border px-3 py-3", contentClassName)}
+      >
+        {children}
+      </CollapsibleContent>
+    </Collapsible>
+  );
+}
+
+export type ShareAgentsSectionProps = Omit<
+  ShareDisclosureSectionProps,
+  "label" | "fallbackLabel"
+> & { label?: ReactNode };
+
+/** Shared expandable boundary for agent-readable sharing details. */
+export function ShareAgentsSection({
+  label = "Share with agents",
+  ...props
+}: ShareAgentsSectionProps) {
+  return (
+    <ShareDisclosureSection
+      {...props}
+      label={label}
+      fallbackLabel="Share with agents"
+    />
+  );
+}
+
+export type SharePeopleSectionProps = Omit<
+  ShareDisclosureSectionProps,
+  "label" | "fallbackLabel"
+> & { label?: ReactNode };
+
+/** Shared expandable boundary for individual people access. */
+export function SharePeopleSection({
+  label = "People with access",
+  ...props
+}: SharePeopleSectionProps) {
+  return (
+    <ShareDisclosureSection
+      {...props}
+      label={label}
+      fallbackLabel="People with access"
+    />
+  );
+}

package/src/sharing/VisibilityBadge.spec.ts

@@ -0,0 +1,96 @@
+import { IconLock, IconUsersGroup, IconWorld } from "@tabler/icons-react";
+import type { ReactElement } from "react";
+import { describe, expect, it } from "vitest";
+
+import { VisibilityBadge } from "./VisibilityBadge.js";
+
+/**
+ * VisibilityBadge is a plain function component with no hooks or DOM access,
+ * so we can call it directly (no render, no jsdom) and inspect the React
+ * element object the JSX runtime builds. This locks down the visibility ->
+ * icon/label mapping and the derived-size math without needing a DOM
+ * environment.
+ */
+
+interface SpanStyle {
+  display: string;
+  alignItems: string;
+  gap: number;
+  fontSize: number;
+  color: string;
+}
+
+interface SpanElement extends ReactElement {
+  type: "span";
+  props: {
+    className?: string;
+    style: SpanStyle;
+    children: [ReactElement<{ size: number }>, string];
+  };
+}
+
+function renderBadge(...args: Parameters<typeof VisibilityBadge>): SpanElement {
+  return VisibilityBadge(...args) as unknown as SpanElement;
+}
+
+describe("VisibilityBadge", () => {
+  it("renders the public icon and label", () => {
+    const el = renderBadge({ visibility: "public" });
+    expect(el.type).toBe("span");
+    const [icon, label] = el.props.children;
+    expect(icon.type).toBe(IconWorld);
+    expect(label).toBe("Public");
+  });
+
+  it("renders the org icon and label", () => {
+    const el = renderBadge({ visibility: "org" });
+    const [icon, label] = el.props.children;
+    expect(icon.type).toBe(IconUsersGroup);
+    expect(label).toBe("Org");
+  });
+
+  it("renders the private icon and label", () => {
+    const el = renderBadge({ visibility: "private" });
+    const [icon, label] = el.props.children;
+    expect(icon.type).toBe(IconLock);
+    expect(label).toBe("Private");
+  });
+
+  it("falls back to private when visibility is null", () => {
+    const el = renderBadge({ visibility: null });
+    const [icon, label] = el.props.children;
+    expect(icon.type).toBe(IconLock);
+    expect(label).toBe("Private");
+  });
+
+  it("falls back to private when visibility is undefined", () => {
+    const el = renderBadge({ visibility: undefined });
+    const [icon, label] = el.props.children;
+    expect(icon.type).toBe(IconLock);
+    expect(label).toBe("Private");
+  });
+
+  it("applies a custom size to both the span font size and the icon size", () => {
+    const el = renderBadge({ visibility: "public", size: 20 });
+    expect(el.props.style.fontSize).toBe(20);
+    const [icon] = el.props.children;
+    expect(icon.props.size).toBe(22);
+  });
+
+  it("defaults size to 12 for the span and 14 for the icon when omitted", () => {
+    const el = renderBadge({ visibility: "public" });
+    expect(el.props.style.fontSize).toBe(12);
+    const [icon] = el.props.children;
+    expect(icon.props.size).toBe(14);
+  });
+
+  it("passes className through to the span", () => {
+    const el = renderBadge({ visibility: "public", className: "my-badge" });
+    expect(el.props.className).toBe("my-badge");
+  });
+
+  it("always uses the muted-foreground color token", () => {
+    const el = renderBadge({ visibility: "org" });
+    expect(el.props.style.color).toBe("hsl(var(--muted-foreground))");
+  });
+});

package/src/sharing/VisibilityBadge.tsx

@@ -0,0 +1,37 @@
+import { IconLock, IconUsersGroup, IconWorld } from "@tabler/icons-react";
+
+export interface VisibilityBadgeProps {
+  visibility: "private" | "org" | "public" | null | undefined;
+  size?: number;
+  className?: string;
+}
+
+/**
+ * Tiny visibility chip for list views. Renders a small icon + label so users
+ * can spot shared/public resources at a glance.
+ */
+export function VisibilityBadge({
+  visibility,
+  size = 12,
+  className,
+}: VisibilityBadgeProps) {
+  const v = visibility ?? "private";
+  const Icon =
+    v === "public" ? IconWorld : v === "org" ? IconUsersGroup : IconLock;
+  const label = v === "public" ? "Public" : v === "org" ? "Org" : "Private";
+  return (
+    <span
+      className={className}
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        gap: 4,
+        fontSize: size,
+        color: "hsl(var(--muted-foreground))",
+      }}
+    >
+      <Icon size={size + 2} />
+      {label}
+    </span>
+  );
+}