proto-plugin 0.1.0

package/src/components/prototypes/prototype-variant-explorer.tsx

@@ -0,0 +1,347 @@
+"use client";
+
+import useCopyToClipboard from "@prototype/lib/use-copy-to-clipboard";
+import { PrototypeControlGroup } from "@prototype/components/prototypes/prototype-control";
+import { PrototypeDesignBriefModal } from "@prototype/components/prototypes/prototype-design-brief-modal";
+import { PrototypeDesignBriefPanel } from "@prototype/components/prototypes/prototype-design-brief-panel";
+import {
+  PrototypeComponent,
+  usePrototypeSlug,
+} from "@prototype/components/prototypes/prototype-target";
+import { PrototypeVariantTabs } from "@prototype/components/prototypes/prototype-variant-tabs";
+import {
+  buildBriefOverviewCopyText,
+  type DesignExplorationConfig,
+} from "@prototype/lib/prototypes/design-exploration-types";
+import { usePrototypeReviewOptional } from "@prototype/lib/prototypes/prototype-review-context";
+import { useDesignExplorationDefault } from "@prototype/lib/prototypes/use-design-exploration-default";
+import { usePersistedLocalString } from "@prototype/lib/prototypes/use-persisted-local-state";
+import { ChevronDown, ChevronUp, LayoutGrid } from "lucide-react";
+import { useEffect, useMemo, useState } from "react";
+
+const OVERVIEW_CONTROL_BUTTON_CLASS = "tool-toolbar-button";
+
+const OVERVIEW_TOOLBAR_CLASS = "tool-toolbar pointer-events-auto";
+
+type PrototypeVariantExplorerProps<TVariant extends string> =
+  DesignExplorationConfig<TVariant> & {
+    /** Stable id for the Mobbin gallery root (registered in component-ids.ts). */
+    mobbinGalleryId?: string;
+    /** When false, caller wraps with PrototypeComponent id={componentIdPrefix}. */
+    wrapRoot?: boolean;
+    /**
+     * When true, only registers sidebar content — skips rendering the active
+     * variant in the page tree. Use for hidden hosts that exist solely to keep
+     * design explorations available in the review sidebar.
+     */
+    registerOnly?: boolean;
+    /** When set, registers this exploration in the review sidebar. */
+    variantSet?: {
+      id: string;
+      label: string;
+    };
+  };
+
+export function PrototypeVariantExplorer<TVariant extends string>({
+  componentIdPrefix,
+  variantTabsIdPrefix,
+  storageKeyPrefix,
+  variant,
+  onVariantChange,
+  options,
+  rationale,
+  renderers,
+  brief,
+  context,
+  mobbin,
+  variantsSection,
+  variantTabAriaLabel = "variant",
+  mobbinGalleryId = "mobbin-inspiration-gallery",
+  wrapRoot = true,
+  registerOnly = false,
+  briefConfigFilePath,
+  variantSet,
+}: PrototypeVariantExplorerProps<TVariant>) {
+  const review = usePrototypeReviewOptional();
+  const slug = usePrototypeSlug();
+  const validValues = useMemo(
+    () => options.map((option) => option.value),
+    [options],
+  );
+  const {
+    effectiveDefault,
+    setDefaultVariant,
+  } = useDesignExplorationDefault({
+    slug,
+    storageKeyPrefix,
+    validValues,
+  });
+  const [notesExpanded, setNotesExpanded] = useState(false);
+  const [overviewOpen, setOverviewOpen] = useState(false);
+  const { copy: copyOverview, icon: copyIcon } = useCopyToClipboard();
+  const { value: overviewTitle } = usePersistedLocalString(
+    `${storageKeyPrefix}-overview-title`,
+    brief.titleDefault,
+  );
+  const { value: overviewDescription } = usePersistedLocalString(
+    `${storageKeyPrefix}-overview-description`,
+    brief.descriptionDefault,
+  );
+
+  const fallbackVariant = options[0]?.value;
+  const activeRationale =
+    rationale[variant] ?? (fallbackVariant ? rationale[fallbackVariant] : undefined);
+  const ActiveVariantRenderer =
+    renderers[variant] ?? (fallbackVariant ? renderers[fallbackVariant] : null);
+  const hideInlineControls = Boolean(review);
+
+  const briefPanelProps = useMemo(
+    () => ({
+      componentIdPrefix,
+      galleryId: mobbinGalleryId,
+      storageKeyPrefix,
+      brief,
+      context,
+      mobbin,
+      variantsSection,
+      variant,
+      onVariantChange,
+      options,
+      rationale,
+      renderers,
+      defaultVariantValue: effectiveDefault,
+      onSetDefaultVariant: setDefaultVariant,
+      briefConfigFilePath,
+    }),
+    [
+      brief,
+      briefConfigFilePath,
+      componentIdPrefix,
+      context,
+      effectiveDefault,
+      mobbin,
+      mobbinGalleryId,
+      onVariantChange,
+      options,
+      rationale,
+      renderers,
+      setDefaultVariant,
+      storageKeyPrefix,
+      variant,
+      variantsSection,
+    ],
+  );
+
+  const sidebarPanel = useMemo(
+    () => (
+      <PrototypeDesignBriefPanel
+        {...briefPanelProps}
+        layout="sidebar"
+        className="min-h-0"
+      />
+    ),
+    [briefPanelProps],
+  );
+
+  const sidebarRegistrationKey = useMemo(
+    () =>
+      [
+        variant,
+        effectiveDefault,
+        overviewTitle,
+        overviewDescription,
+        options.map((option) => option.value).join(","),
+      ].join("|"),
+    [variant, effectiveDefault, overviewTitle, overviewDescription, options],
+  );
+
+  const variantSetId = variantSet?.id ?? null;
+  const hasReview = review != null;
+
+  useEffect(() => {
+    if (!review) return;
+
+    if (variantSetId) {
+      review.registerVariantSidebarContent(variantSetId, sidebarPanel);
+      return;
+    }
+
+    review.registerLegacyVariantSidebarContent(sidebarPanel);
+  }, [hasReview, review, sidebarPanel, variantSetId]);
+
+  useEffect(() => {
+    if (!review) return;
+
+    if (variantSetId) {
+      review.updateVariantSidebarContent(variantSetId, sidebarPanel);
+      return;
+    }
+
+    review.updateLegacyVariantSidebarContent(sidebarPanel);
+    // Gate this effect on `sidebarRegistrationKey` (a serialized snapshot of the
+    // meaningful sidebar content), NOT on `review` or `sidebarPanel`:
+    //  - `review` identity changes every time updateVariant*SidebarContent bumps
+    //    variantSidebarRevision, and `sidebarPanel` is rebuilt on every render
+    //    (its config objects are not referentially stable). Depending on either
+    //    re-triggers this effect, which bumps the revision again -> infinite loop.
+    //  - The closure still reads the latest `sidebarPanel`, and the key changes
+    //    whenever the rendered content actually changes, so fresh content is
+    //    always pushed.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [hasReview, variantSetId, sidebarRegistrationKey]);
+
+  useEffect(() => {
+    if (!review || variantSetId) return;
+
+    review.setLegacyVariantsAvailable(true);
+    return () => review.setLegacyVariantsAvailable(false);
+  }, [hasReview, variantSetId]);
+
+  const controls = useMemo(
+    () => (
+      <div className="relative">
+        <PrototypeControlGroup className="flex justify-end">
+          <div className="relative">
+            <div className="flex flex-wrap items-center gap-2">
+              <PrototypeVariantTabs
+                idPrefix={variantTabsIdPrefix}
+                options={options}
+                value={variant}
+                onValueChange={onVariantChange}
+                keyboardScopeActive={!overviewOpen}
+                variantTabAriaLabel={variantTabAriaLabel}
+                defaultVariantValue={effectiveDefault}
+              />
+
+              <div className={OVERVIEW_TOOLBAR_CLASS}>
+                <PrototypeComponent id={`${componentIdPrefix}.overview-copy-brief`}>
+                  <button
+                    type="button"
+                    className={OVERVIEW_CONTROL_BUTTON_CLASS}
+                    onClick={() =>
+                      copyOverview(
+                        buildBriefOverviewCopyText(
+                          overviewTitle.trim() || brief.titleDefault,
+                          overviewDescription.trim() || brief.descriptionDefault,
+                        ),
+                      )
+                    }
+                    aria-label="Copy overview"
+                  >
+                    {copyIcon}
+                  </button>
+                </PrototypeComponent>
+
+                <PrototypeComponent id={`${componentIdPrefix}.overview-trigger`}>
+                  <button
+                    type="button"
+                    className={OVERVIEW_CONTROL_BUTTON_CLASS}
+                    onClick={() => setOverviewOpen(true)}
+                    aria-label="View all variants"
+                  >
+                    <LayoutGrid className="size-3.5" />
+                  </button>
+                </PrototypeComponent>
+
+                <button
+                  type="button"
+                  className={OVERVIEW_CONTROL_BUTTON_CLASS}
+                  onClick={() => setNotesExpanded((expanded) => !expanded)}
+                  aria-expanded={notesExpanded}
+                  aria-controls={`${componentIdPrefix}-notes`}
+                  aria-label={notesExpanded ? "Hide notes" : "Show notes"}
+                >
+                  {notesExpanded ? (
+                    <ChevronUp className="size-3.5" />
+                  ) : (
+                    <ChevronDown className="size-3.5" />
+                  )}
+                </button>
+              </div>
+            </div>
+
+            {notesExpanded && activeRationale ? (
+              <PrototypeComponent
+                id={`${componentIdPrefix}.rationale`}
+                className="border-border bg-muted absolute right-0 top-full z-10 mt-2 max-w-md rounded-lg border px-3 py-2.5 text-left"
+              >
+                <div
+                  id={`${componentIdPrefix}-notes`}
+                  className="flex flex-col gap-2"
+                >
+                  <p className="text-sm leading-relaxed">
+                    <span className="text-foreground font-medium">Good</span>
+                    {" · "}
+                    <span className="text-muted-foreground">
+                      {activeRationale.good}
+                    </span>
+                  </p>
+                  <p className="text-sm leading-relaxed">
+                    <span className="text-foreground font-medium">Bad</span>
+                    {" · "}
+                    <span className="text-muted-foreground">
+                      {activeRationale.bad}
+                    </span>
+                  </p>
+                </div>
+              </PrototypeComponent>
+            ) : null}
+          </div>
+        </PrototypeControlGroup>
+      </div>
+    ),
+    [
+      activeRationale,
+      brief.descriptionDefault,
+      brief.titleDefault,
+      componentIdPrefix,
+      copyIcon,
+      copyOverview,
+      effectiveDefault,
+      notesExpanded,
+      onVariantChange,
+      options,
+      overviewDescription,
+      overviewOpen,
+      overviewTitle,
+      variant,
+      variantTabAriaLabel,
+      variantTabsIdPrefix,
+    ],
+  );
+
+  const inlineControls = wrapRoot ? (
+    <PrototypeComponent id={componentIdPrefix}>{controls}</PrototypeComponent>
+  ) : (
+    controls
+  );
+
+  return (
+    <div className="relative">
+      {!hideInlineControls ? inlineControls : null}
+
+      {!hideInlineControls ? (
+        <PrototypeDesignBriefModal
+          open={overviewOpen}
+          onOpenChange={setOverviewOpen}
+          componentIdPrefix={componentIdPrefix}
+          galleryId={mobbinGalleryId}
+          storageKeyPrefix={storageKeyPrefix}
+          brief={brief}
+          context={context}
+          mobbin={mobbin}
+          variantsSection={variantsSection}
+          variant={variant}
+          onVariantChange={onVariantChange}
+          options={options}
+          rationale={rationale}
+          renderers={renderers}
+          defaultVariantValue={effectiveDefault}
+          onSetDefaultVariant={setDefaultVariant}
+        />
+      ) : null}
+
+      {!registerOnly && ActiveVariantRenderer ? ActiveVariantRenderer() : null}
+    </div>
+  );
+}

package/src/components/prototypes/prototype-variant-rationale-panel.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+import { Panel, PanelSection } from "@prototype/components/platform-ui/panel";
+import { PrototypeComponent } from "@prototype/components/prototypes/prototype-target";
+import type { DesignExplorationRationale } from "@prototype/lib/prototypes/design-exploration-types";
+import { cn } from "@prototype/lib/utils";
+
+type PrototypeVariantRationalePanelProps = {
+  componentId: string;
+  rationale: DesignExplorationRationale;
+  expanded: boolean;
+  onExpandedChange: (expanded: boolean) => void;
+  layout?: "default" | "sidebar";
+  bodyClassName?: string;
+};
+
+export function PrototypeVariantRationalePanel({
+  componentId,
+  rationale,
+  expanded,
+  onExpandedChange,
+  layout = "default",
+  bodyClassName,
+}: PrototypeVariantRationalePanelProps) {
+  const isSidebar = layout === "sidebar";
+
+  return (
+    <PrototypeComponent id={componentId}>
+      <Panel
+        className={cn(
+          "overflow-hidden rounded-lg bg-muted",
+          isSidebar && "rounded-md",
+        )}
+      >
+        <PanelSection
+          title="Notes"
+          expanded={expanded}
+          onExpandedChange={onExpandedChange}
+          headerClassName={isSidebar ? "px-2.5 py-2 normal-case" : undefined}
+          className="border-t-0"
+        >
+          <p className={cn("leading-relaxed", bodyClassName)}>
+            {rationale.good} {rationale.bad}
+          </p>
+        </PanelSection>
+      </Panel>
+    </PrototypeComponent>
+  );
+}

package/src/components/prototypes/prototype-variant-tabs.tsx

@@ -0,0 +1,207 @@
+"use client";
+
+import pillStyles from "@prototype/components/prototypes/prototype-floating-pill.module.scss";
+import { PrototypeComponent } from "@prototype/components/prototypes/prototype-target";
+import { Tabs, TabsList, TabsTrigger } from "@prototype/components/ui/tabs";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "@prototype/components/ui/tooltip";
+import { cn } from "@prototype/lib/utils";
+import {
+  getAdjacentDesignExplorationVariant,
+  type DesignExplorationVariantOption,
+} from "@prototype/lib/prototypes/design-exploration-types";
+import { useCallback, useEffect, useState } from "react";
+
+type PrototypeVariantTabsProps<TVariant extends string> = {
+  idPrefix: string;
+  options: DesignExplorationVariantOption<TVariant>[];
+  value: TVariant;
+  onValueChange: (value: TVariant) => void;
+  /** When true, ArrowLeft/ArrowRight cycle variants (unless a lightbox is open). */
+  keyboardScopeActive?: boolean;
+  className?: string;
+  /** Disambiguates comment targets when multiple tab strips could mount. */
+  surface?: "inline" | "modal";
+  variantTabAriaLabel?: string;
+  /** Shown with a marker when this option is not the active tab. */
+  defaultVariantValue?: TVariant;
+  /** Dark styling for the review chrome floating popover. */
+  appearance?: "light" | "dark";
+  /** Tab trigger content — footer chrome uses labels; modals default to index numbers. */
+  tabDisplay?: "index" | "label";
+};
+
+function getVariantTabsId(idPrefix: string, surface: "inline" | "modal", segment: string) {
+  return surface === "modal"
+    ? `${idPrefix}.modal.${segment}`
+    : `${idPrefix}.${segment}`;
+}
+
+function isTypingTarget(target: EventTarget | null) {
+  if (!(target instanceof HTMLElement)) return false;
+  const tag = target.tagName;
+  return tag === "INPUT" || tag === "TEXTAREA" || target.isContentEditable;
+}
+
+export function PrototypeVariantTabs<TVariant extends string>({
+  idPrefix,
+  options,
+  value,
+  onValueChange,
+  keyboardScopeActive = true,
+  className,
+  surface = "inline",
+  variantTabAriaLabel = "variant",
+  defaultVariantValue,
+  appearance = "dark",
+  tabDisplay = "index",
+}: PrototypeVariantTabsProps<TVariant>) {
+  const [keyboardNavEngaged, setKeyboardNavEngaged] = useState(false);
+
+  const goPrev = useCallback(() => {
+    onValueChange(getAdjacentDesignExplorationVariant(options, value, "prev"));
+  }, [onValueChange, options, value]);
+
+  const goNext = useCallback(() => {
+    onValueChange(getAdjacentDesignExplorationVariant(options, value, "next"));
+  }, [onValueChange, options, value]);
+
+  const engageKeyboardNav = useCallback(() => {
+    setKeyboardNavEngaged(true);
+  }, []);
+
+  const handleArrowNavigation = useCallback(
+    (direction: "prev" | "next") => {
+      if (direction === "prev") {
+        goPrev();
+      } else {
+        goNext();
+      }
+    },
+    [goNext, goPrev],
+  );
+
+  useEffect(() => {
+    if (!keyboardScopeActive) {
+      setKeyboardNavEngaged(false);
+    }
+  }, [keyboardScopeActive]);
+
+  useEffect(() => {
+    if (!keyboardScopeActive || !keyboardNavEngaged) return;
+
+    function handleKeyDown(event: globalThis.KeyboardEvent) {
+      if (event.key !== "ArrowLeft" && event.key !== "ArrowRight") return;
+      if (isTypingTarget(event.target)) return;
+      if (document.querySelector("[data-mobbin-lightbox-open]")) return;
+
+      event.preventDefault();
+      handleArrowNavigation(event.key === "ArrowLeft" ? "prev" : "next");
+    }
+
+    document.addEventListener("keydown", handleKeyDown, true);
+    return () => document.removeEventListener("keydown", handleKeyDown, true);
+  }, [handleArrowNavigation, keyboardNavEngaged, keyboardScopeActive]);
+
+  const activeIndex = options.findIndex((option) => option.value === value);
+  const rootId = surface === "modal" ? `${idPrefix}.modal` : idPrefix;
+  const isDark = appearance === "dark";
+  const showLabel = tabDisplay === "label";
+
+  function getTabTriggerContent(
+    option: DesignExplorationVariantOption<TVariant>,
+    index: number,
+  ) {
+    return showLabel ? option.label : index + 1;
+  }
+
+  return (
+    <PrototypeComponent
+      id={rootId}
+      className={cn("min-w-0 shrink-0", className)}
+      onPointerDown={engageKeyboardNav}
+    >
+      <Tabs
+        value={value}
+        onValueChange={(nextValue) => {
+          engageKeyboardNav();
+          onValueChange(nextValue as TVariant);
+        }}
+        className="min-w-0"
+      >
+        <PrototypeComponent
+          id={getVariantTabsId(idPrefix, surface, "list")}
+          className="min-w-0 overflow-x-auto"
+        >
+          <TooltipProvider delayDuration={200}>
+            <TabsList
+              className={cn(
+                "inline-flex w-max",
+                isDark && pillStyles.variantsTabsList,
+              )}
+            >
+              {options.map((option, index) => {
+                const isDefaultOption =
+                  defaultVariantValue !== undefined &&
+                  option.value === defaultVariantValue;
+                const isDefaultWhenUnselected =
+                  isDefaultOption && option.value !== value;
+                const tabClassName = cn(
+                  "shrink-0",
+                  !showLabel && "min-w-8 tabular-nums",
+                  showLabel && "max-w-[10rem] truncate px-2.5",
+                  !isDark && !showLabel && "px-2",
+                  isDefaultWhenUnselected &&
+                    (isDark
+                      ? pillStyles.variantsDefaultTab
+                      : "bg-muted text-foreground"),
+                  isDark && pillStyles.variantsTab,
+                );
+                const tabId = `${idPrefix}-tab-${surface}-${option.value}`;
+                const defaultTabAriaLabel = `${variantTabAriaLabel} ${index + 1}: ${option.label}, selected`;
+
+                if (!isDefaultOption) {
+                  return (
+                    <TabsTrigger
+                      key={option.value}
+                      value={option.value}
+                      id={tabId}
+                      aria-label={`${variantTabAriaLabel} ${index + 1}: ${option.label}`}
+                      className={tabClassName}
+                    >
+                      {getTabTriggerContent(option, index)}
+                    </TabsTrigger>
+                  );
+                }
+
+                return (
+                  <Tooltip key={option.value}>
+                    <TooltipTrigger asChild>
+                      <TabsTrigger
+                        value={option.value}
+                        id={tabId}
+                        aria-label={defaultTabAriaLabel}
+                        className={tabClassName}
+                      >
+                        {getTabTriggerContent(option, index)}
+                      </TabsTrigger>
+                    </TooltipTrigger>
+                    <TooltipContent side="top">Selected</TooltipContent>
+                  </Tooltip>
+                );
+              })}
+            </TabsList>
+          </TooltipProvider>
+        </PrototypeComponent>
+      </Tabs>
+
+      <span className="text-xs text-muted-foreground sr-only" aria-live="polite">
+        {`${activeIndex + 1} of ${options.length}: ${options[activeIndex]?.label ?? ""}`}
+      </span>
+    </PrototypeComponent>
+  );
+}