@drawnagency/primitives 0.1.113 → 0.1.114

package/src/components/sections/SectionSummary/index.tsx

@@ -0,0 +1,149 @@
+import { useContext } from "react";
+import { z } from "zod";
+import { ListChecks } from "lucide-react";
+import { defineSection } from "../../../lib/registry";
+import { LinkValueSchema, DEFAULT_LINK } from "../../../schemas/link";
+import { SummaryAnchorsContext } from "../../shared/SummaryAnchorsContext";
+import { SectionSummaryBlock, type SectionSummaryOptions } from "./SectionSummaryBlock";
+import { SectionSummarySettings } from "./SectionSummarySettings";
+
+// The end-of-section TL;DR plate, promoted from Siete's site-local section (#59).
+// The type id and content shape are unchanged, so existing Siete content loads
+// as-is; nav/navLabel are the only additions.
+
+const itemSchema = z.object({
+  headline: z.string().default("").describe("The principle, short and bold, e.g. \"Saturation > Subtlety\"."),
+  explainer: z
+    .string()
+    .default("")
+    .describe("Optional one-sentence explainer rendered softly beneath the headline."),
+  link: LinkValueSchema.default(DEFAULT_LINK).describe(
+    "Optional jump-link trailing the principle, back to the sub-section it distills. Set with the link picker: an internal page/section (label auto-derived from the page or section name) or an external URL. An empty link renders nothing, but its space is reserved so the layout stays stable.",
+  ),
+  linkLabel: z
+    .string()
+    .default("")
+    .describe(
+      "The jump-link label. Auto-derived from the linked page or section name for internal links (kept in sync as you edit); for external links it falls back to the URL.",
+    ),
+});
+
+const schema = z.object({
+  type: z.literal("section_summary"),
+  content: z.object({
+    kicker: z
+      .string()
+      .default("")
+      .describe('Uppercase label in the plate\'s top-left, e.g. "Brand Color — Summary".'),
+    accent: z
+      .string()
+      .default("")
+      .describe('Script flourish in the plate\'s top-right, e.g. "tl;dr".'),
+    items: z
+      .array(itemSchema)
+      .default([])
+      .describe("The summary principles, in display order (numbered automatically)."),
+    footNote: z
+      .string()
+      .default("")
+      .describe(
+        'Contextual note in the footer\'s bottom-left, e.g. "Brand Color · 06 principles". Empty = auto "<count> principles".',
+      ),
+  }),
+  options: z
+    .object({
+      showAccent: z.boolean().describe("Show the script accent (default true).").optional(),
+      showFooter: z.boolean().describe("Show the footer row (default true).").optional(),
+      showCopy: z
+        .boolean()
+        .describe("Show the copy-summary action in the footer (default true).")
+        .optional(),
+      numbered: z.boolean().describe("Show the accent-colored item numerals (default true).").optional(),
+      nav: z
+        .enum(["off", "heading", "subheading"])
+        .describe(
+          'Put this plate in the page nav: "heading" = top level (like a Link Heading), "subheading" = nested under the preceding Link Heading (dropped from the nav if there is none, like a Sub Heading). Absent or "off" = not in the nav.',
+        )
+        .optional(),
+      navLabel: z
+        .string()
+        .describe(
+          "The plate's nav entry text; REQUIRED while nav is on (no label = no entry). Its anchor is derived from it, suffixed -2, -3… if another anchor on the page already has it.",
+        )
+        .optional(),
+    })
+    .default({}),
+});
+
+export default defineSection({
+  type: "section_summary",
+  category: "brand-guide",
+  label: "TL;DR / Summary",
+  icon: <ListChecks size={18} />,
+  schema,
+  authoringNote:
+    "An end-of-section TL;DR plate: numbered principles (bold headline + optional one-sentence explainer) with " +
+    "an optional jump-link trailing each explainer back to the sub-section it distills. Place it as the LAST " +
+    "block of a major section. Each principle's jump-link is set with the link picker — an internal page/section " +
+    "(its label auto-derived from the page or section name) or an external URL; an empty link renders nothing. " +
+    'The footer shows footNote (or an auto "<count> principles" note) plus a copy action that puts the whole ' +
+    'summary on the clipboard as plain text (kicker + "• headline — explainer" lines). Fully functional on the ' +
+    "logged-out viewer — no hydration. Optionally appears in the page nav (options.nav heading/subheading with a " +
+    "required options.navLabel). Headlines/explainers are composed from truths in the section above; never " +
+    "introduce facts here that the section itself does not state.",
+  component: function SectionSummarySection({ content, options, onChange, openModal }) {
+    const c = content.content;
+    const set = (patch: Partial<typeof c>) => onChange?.({ ...content, content: { ...c, ...patch } });
+    const id = (content as { id?: string }).id;
+    const opts = (options ?? {}) as SectionSummaryOptions;
+    const editorAnchor = useContext(SummaryAnchorsContext)[id ?? ""];
+    const navAnchor = editorAnchor?.anchor ?? (content as { navAnchor?: string }).navAnchor;
+    const navOn = opts.nav === "heading" || opts.nav === "subheading";
+    const navHint = !navOn
+      ? undefined
+      : !opts.navLabel?.trim()
+        ? "Not in the nav: add a nav label in Settings."
+        : editorAnchor && !editorAnchor.inNav
+          ? "Not in the nav: a Subheading needs a Link Heading above it."
+          : undefined;
+    return (
+      <SectionSummaryBlock
+        sectionId={id}
+        kicker={c.kicker}
+        accent={c.accent}
+        footNote={c.footNote}
+        items={c.items}
+        options={opts}
+        isEditMode={!!onChange}
+        openModal={openModal}
+        onKickerChange={onChange ? (kicker) => set({ kicker }) : undefined}
+        onAccentChange={onChange ? (accent) => set({ accent }) : undefined}
+        onFootNoteChange={onChange ? (footNote) => set({ footNote }) : undefined}
+        onItemsChange={onChange ? (items) => set({ items }) : undefined}
+        navAnchor={navAnchor}
+        navHint={navHint}
+      />
+    );
+  },
+  // Inserts ready-to-use with one starter row to overwrite — no empty state to
+  // climb out of.
+  defaults: () => ({
+    type: "section_summary" as const,
+    content: {
+      kicker: "Summary",
+      accent: "tl;dr",
+      items: [
+        {
+          headline: "First principle",
+          explainer: "One sentence on why it matters.",
+          link: DEFAULT_LINK,
+          linkLabel: "",
+        },
+      ],
+      footNote: "",
+    },
+    options: {},
+  }),
+  getLabel: (content) => content.content.kicker || "TL;DR / Summary",
+  settingsForm: SectionSummarySettings,
+});

package/src/components/sections/SubHeading/index.tsx

@@ -1,5 +1,5 @@
 import { Heading2 } from "lucide-react";
-import { defineHeadingSection } from "../../primitives/defineHeadingSection";
+import { defineHeadingSection } from "../../primitives/define-heading-section";
 
 export default defineHeadingSection({
   type: "sub_heading",

package/src/components/sections/SubSubHeading/index.tsx

@@ -1,5 +1,5 @@
 import { Heading3 } from "lucide-react";
-import { defineHeadingSection } from "../../primitives/defineHeadingSection";
+import { defineHeadingSection } from "../../primitives/define-heading-section";
 
 export default defineHeadingSection({
   type: "sub_sub_heading",

package/src/components/sections/brand-guide.ts

@@ -2,13 +2,14 @@ import colors from "./Colors";
 import iconList from "./IconList";
 import doDontMedia from "./DoDontMedia";
 import documentSection from "./Document";
+import sectionSummary from "./SectionSummary";
 
 /** Opinionated brand-guide sections. Self-contained subtree: a build that does
- *  not import this module drops these sections (and their cmyk/pantone schemas
- *  and do/dont compositions) entirely. Exposed at
+ *  not import this module drops these sections (and their cmyk/pantone schemas,
+ *  do/dont compositions and the TL;DR plate) entirely. Exposed at
  *  `@drawnagency/primitives/components/sections/brand-guide`. */
 // Un-annotated for the same generic-variance reason as coreSectionDefs.
-export const brandGuideSectionDefs = [colors, iconList, doDontMedia, documentSection];
+export const brandGuideSectionDefs = [colors, iconList, doDontMedia, documentSection, sectionSummary];
 
 export { ColorSpaceSchema, ColorItemSchema } from "./Colors/schema";
 export type { ColorSpace, ColorItem } from "./Colors/schema";

package/src/components/sections/core-sections.ts

@@ -7,6 +7,7 @@ import video from "./Video";
 import button from "./Button";
 import container from "./Container";
 import spacer from "./Spacer";
+import reference from "./Reference";
 
 /** Generic, brand-agnostic built-in sections. A non-brand site can register
  *  exactly these (plus its own custom sections) and tree-shake the brand-guide
@@ -25,4 +26,5 @@ export const coreSectionDefs = [
   button,
   container,
   spacer,
+  reference,
 ];

package/src/components/shared/BrandSwatchesContext.ts

@@ -0,0 +1,13 @@
+import { createContext, useContext } from "react";
+import type { BrandSwatch } from "../../lib/brand-swatches";
+
+/**
+ * Hex values from every Colors section site-wide, for color pickers in
+ * settings forms. A form only receives its own section's values, so EditorShell
+ * provides these from all loaded sections (collectBrandSwatches).
+ */
+export const BrandSwatchesContext = createContext<BrandSwatch[]>([]);
+
+export function useBrandSwatches(): BrandSwatch[] {
+  return useContext(BrandSwatchesContext);
+}

package/src/components/shared/Button.tsx

@@ -1,20 +1,29 @@
-import { forwardRef, type ButtonHTMLAttributes, type ReactNode } from "react";
+import type { AnchorHTMLAttributes, ButtonHTMLAttributes, ReactNode, Ref } from "react";
 import { cn } from "../../lib/cn";
 
 export type ButtonVariant = "primary" | "brand" | "secondary" | "destructive" | "ghost";
 export type ButtonSize = "sm" | "md";
 export type ButtonTone = "neutral" | "destructive";
 
-export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+interface ButtonCommon {
   variant?: ButtonVariant;
   size?: ButtonSize;
   tone?: ButtonTone;
   fullWidth?: boolean;
   isLoading?: boolean;
   loadingLabel?: string;
+  className?: string;
   children?: ReactNode;
 }
 
+// Same discriminated-union shape as Fab: `href` renders an <a> with identical
+// classes (ref excluded — an <a> ref is a different element type, and no
+// caller needs one today); its absence renders a <button> and accepts a ref.
+export type ButtonProps =
+  | ({ href: string } & ButtonCommon & Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "children" | "className">)
+  | ({ href?: undefined; ref?: Ref<HTMLButtonElement> } & ButtonCommon &
+      Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | "className">);
+
 const boxSize: Record<ButtonSize, string> = {
   sm: "rounded px-3 py-1.5 text-xs font-medium",
   md: "rounded px-4 py-2 text-sm font-medium",
@@ -30,48 +39,52 @@ const variantClasses: Record<Exclude<ButtonVariant, "ghost">, string> = {
   brand: "bg-primary text-primary-contrast hover:opacity-90",
   secondary: "border border-base-200 text-base-contrast hover:bg-base-accent",
   destructive:
-    "border border-red-600 text-red-600 hover:bg-red-600 hover:text-white",
+    "border border-danger text-danger hover:bg-danger hover:text-white",
 };
 
 const ghostToneClasses: Record<ButtonTone, string> = {
   neutral: "text-base-contrast-light hover:text-base-contrast",
-  destructive: "text-red-600 hover:text-red-800",
+  destructive: "text-danger hover:text-danger-hover",
 };
 
-export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
-  {
-    variant = "primary",
-    size = "sm",
-    tone = "neutral",
-    fullWidth = false,
-    isLoading = false,
-    loadingLabel,
-    disabled,
-    className,
-    children,
-    ...rest
-  },
-  ref,
-) {
+export function Button({
+  variant = "primary",
+  size = "sm",
+  tone = "neutral",
+  fullWidth = false,
+  isLoading = false,
+  loadingLabel,
+  className,
+  children,
+  ...rest
+}: ButtonProps) {
   const isGhost = variant === "ghost";
-  const resolvedDisabled = disabled || isLoading;
+  const disabled = rest.href === undefined ? rest.disabled || isLoading : false;
   const label = isLoading && loadingLabel ? loadingLabel : children;
 
+  const classes = cn(
+    "inline-flex items-center justify-center transition-colors",
+    "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary",
+    isGhost ? ghostSize[size] : boxSize[size],
+    isGhost ? ghostToneClasses[tone] : variantClasses[variant],
+    fullWidth && "w-full",
+    disabled ? "cursor-not-allowed opacity-50" : "cursor-pointer",
+    className,
+  );
+
+  if (rest.href !== undefined) {
+    return (
+      <a className={classes} {...(rest as AnchorHTMLAttributes<HTMLAnchorElement>)}>
+        {label}
+      </a>
+    );
+  }
+
+  const { ref, disabled: _disabled, ...buttonRest } = rest as { ref?: Ref<HTMLButtonElement> } &
+    ButtonHTMLAttributes<HTMLButtonElement>;
   return (
-    <button
-      ref={ref}
-      disabled={resolvedDisabled}
-      className={cn(
-        "inline-flex items-center justify-center transition-colors",
-        isGhost ? ghostSize[size] : boxSize[size],
-        isGhost ? ghostToneClasses[tone] : variantClasses[variant],
-        fullWidth && "w-full",
-        resolvedDisabled ? "cursor-not-allowed opacity-50" : "cursor-pointer",
-        className,
-      )}
-      {...rest}
-    >
+    <button ref={ref} disabled={disabled} className={classes} {...buttonRest}>
       {label}
     </button>
   );
-});
+}

package/src/components/shared/Checkbox.tsx

@@ -48,18 +48,10 @@ export function Checkbox({
           onChange={(e) => onChange(e.target.checked)}
           className="sr-only"
         />
-        <span
-          aria-hidden="true"
-          className={cn(
-            "flex h-5 w-5 items-center justify-center rounded border transition-colors",
-            checked
-              ? "border-primary bg-primary text-primary-contrast"
-              : "border-base-300 bg-base hover:border-primary",
-            disabled && "pointer-events-none",
-          )}
-        >
-          {checked && <Check size={14} strokeWidth={3} />}
-        </span>
+        <CheckboxBox
+          checked={checked}
+          className={cn(!checked && "hover:border-primary", disabled && "pointer-events-none")}
+        />
       </span>
       {startAdornment}
       <div className="text-sm">
@@ -71,3 +63,20 @@ export function Checkbox({
     </label>
   );
 }
+
+/** The visual square alone, for rows whose own element carries the checkbox
+ *  role (a menu item, a picker row) and so can't nest a labelled input. */
+export function CheckboxBox({ checked, className }: { checked: boolean; className?: string }) {
+  return (
+    <span
+      aria-hidden="true"
+      className={cn(
+        "flex h-5 w-5 shrink-0 items-center justify-center rounded border transition-colors",
+        checked ? "border-primary bg-primary text-primary-contrast" : "border-base-300 bg-base",
+        className,
+      )}
+    >
+      {checked && <Check size={14} strokeWidth={3} />}
+    </span>
+  );
+}

package/src/components/shared/ConfirmDialog.tsx

@@ -0,0 +1,87 @@
+import type { ReactNode } from "react";
+import { Button } from "./Button";
+import { EditorModal } from "../shell/EditorModal";
+
+// Stable identity: EditorModal wires this into useStackedEscape, whose effect
+// deps include it — a fresh `() => {}` literal every render (while `busy`)
+// would tear down and re-add its Escape listener on every render instead of
+// just when `busy` actually flips.
+const NOOP = () => {};
+
+export interface ConfirmDialogProps {
+  isOpen: boolean;
+  title: string;
+  body?: ReactNode;
+  confirmLabel: string;
+  cancelLabel?: string;
+  tone?: "destructive" | "neutral";
+  busy?: boolean;
+  busyLabel?: string;
+  /** The typed-name page delete gates on this. */
+  confirmDisabled?: boolean;
+  onConfirm: () => void;
+  onCancel: () => void;
+  /**
+   * Renders title/body/buttons with no `EditorModal` wrapper — for a confirm
+   * that appears inside an ALREADY-OPEN `EditorModal` (PagesModal's typed-name
+   * delete, HistoryChangesModal's restore mode-swap). Two nested EditorModals
+   * would each register their own document Escape listener, so one Escape
+   * would close both.
+   */
+  embedded?: boolean;
+}
+
+export function ConfirmDialog({
+  isOpen,
+  title,
+  body,
+  confirmLabel,
+  cancelLabel = "Cancel",
+  tone = "destructive",
+  busy = false,
+  busyLabel,
+  confirmDisabled = false,
+  onConfirm,
+  onCancel,
+  embedded = false,
+}: ConfirmDialogProps) {
+  if (!isOpen) return null;
+
+  const buttons = (
+    <div className="flex justify-end gap-3">
+      <Button type="button" variant="secondary" size="md" onClick={onCancel} disabled={busy}>
+        {cancelLabel}
+      </Button>
+      <Button
+        type="button"
+        variant={tone === "destructive" ? "destructive" : "primary"}
+        size="md"
+        onClick={onConfirm}
+        disabled={confirmDisabled}
+        isLoading={busy}
+        loadingLabel={busyLabel}
+      >
+        {confirmLabel}
+      </Button>
+    </div>
+  );
+
+  if (embedded) {
+    return (
+      <div className="flex flex-col gap-3">
+        <h4 className="text-base font-semibold text-base-contrast">{title}</h4>
+        {body}
+        {buttons}
+      </div>
+    );
+  }
+
+  return (
+    <EditorModal isOpen={isOpen} onClose={busy ? NOOP : onCancel} title={title} size="standard">
+      <div className="flex flex-col gap-3">
+        {body}
+        {buttons}
+      </div>
+    </EditorModal>
+  );
+}

package/src/components/shared/ConfirmInline.tsx

@@ -0,0 +1,90 @@
+import { useEffect, useRef, type ReactNode, type RefObject } from "react";
+import { cn } from "../../lib/cn";
+import { Button } from "./Button";
+
+export type ConfirmTone = "destructive" | "neutral";
+
+const toneClasses: Record<ConfirmTone, string> = {
+  destructive: "border-danger bg-danger-bg text-danger",
+  neutral: "border-base-200 bg-base text-base-contrast",
+};
+
+export interface ConfirmInlineProps {
+  message: ReactNode;
+  confirmLabel: string;
+  cancelLabel?: string;
+  tone: ConfirmTone;
+  busy?: boolean;
+  confirmDisabled?: boolean;
+  /** Overrides the confirm button's accessible name when the visible label is
+   *  ambiguous across multiple rows (NavGroupRow's pinned "Confirm delete"). */
+  confirmAriaLabel?: string;
+  /** Sits between Cancel and confirm as `Button variant="secondary"` — the
+   *  folder delete's "Move contents to parent" is the one user today. */
+  secondaryAction?: { label: string; onClick: () => void };
+  onConfirm: () => void;
+  onCancel: () => void;
+  /** Focus returns here on unmount — the row's trigger button, typically. */
+  returnFocusTo?: RefObject<HTMLElement | null>;
+}
+
+export function ConfirmInline({
+  message,
+  confirmLabel,
+  cancelLabel = "Cancel",
+  tone,
+  busy = false,
+  confirmDisabled = false,
+  confirmAriaLabel,
+  secondaryAction,
+  onConfirm,
+  onCancel,
+  returnFocusTo,
+}: ConfirmInlineProps) {
+  const cancelRef = useRef<HTMLButtonElement>(null);
+
+  // Focus moves to Cancel on mount and back to the trigger on unmount — a
+  // destructive/neutral confirm appearing inline (not in a trapped modal)
+  // still owes a keyboard user a predictable landing spot.
+  useEffect(() => {
+    cancelRef.current?.focus();
+    return () => {
+      returnFocusTo?.current?.focus();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- mount/unmount only
+  }, []);
+
+  return (
+    <div
+      role="alertdialog"
+      aria-live="assertive"
+      className={cn(
+        "flex flex-col items-center gap-2 rounded-lg border px-4 py-3 lg:flex-row lg:justify-between",
+        toneClasses[tone],
+      )}
+    >
+      <p className="text-center text-sm lg:text-left">{message}</p>
+      <div className="flex shrink-0 flex-wrap items-center justify-end gap-2">
+        <Button type="button" ref={cancelRef} variant="secondary" size="sm" onClick={onCancel} disabled={busy}>
+          {cancelLabel}
+        </Button>
+        {secondaryAction && (
+          <Button type="button" variant="secondary" size="sm" onClick={secondaryAction.onClick} disabled={busy}>
+            {secondaryAction.label}
+          </Button>
+        )}
+        <Button
+          type="button"
+          variant={tone === "destructive" ? "destructive" : "primary"}
+          size="sm"
+          onClick={onConfirm}
+          disabled={confirmDisabled}
+          isLoading={busy}
+          aria-label={confirmAriaLabel}
+        >
+          {confirmLabel}
+        </Button>
+      </div>
+    </div>
+  );
+}

package/src/components/shared/ErrorBoundary.tsx

@@ -1,4 +1,5 @@
 import { Component, type ReactNode, type ErrorInfo } from "react";
+import { AlertTriangle } from "lucide-react";
 import { cn } from "../../lib/cn";
 import { Button } from "./Button";
 
@@ -46,36 +47,23 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
         <div
           role="alert"
           className={cn(
-            "flex flex-col items-center justify-center gap-3 rounded border border-red-200 bg-red-50 px-6 py-10 text-center",
-            "dark:border-red-900/40 dark:bg-red-950/20",
+            "flex flex-col items-center justify-center gap-3 rounded border border-danger bg-danger-bg px-6 py-10 text-center",
           )}
         >
-          <svg
-            xmlns="http://www.w3.org/2000/svg"
-            viewBox="0 0 20 20"
-            fill="currentColor"
-            className="h-6 w-6 text-red-500"
-            aria-hidden="true"
-          >
-            <path
-              fillRule="evenodd"
-              d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-8-5a.75.75 0 01.75.75v4.5a.75.75 0 01-1.5 0v-4.5A.75.75 0 0110 5zm0 10a1 1 0 100-2 1 1 0 000 2z"
-              clipRule="evenodd"
-            />
-          </svg>
+          <AlertTriangle className="h-6 w-6 text-danger" aria-hidden="true" />
 
-          <p className="text-sm font-medium text-red-700 dark:text-red-400">
+          <p className="text-sm font-medium text-danger">
             This section couldn&apos;t be rendered
           </p>
 
           {this.props.label && (
-            <p className="text-xs text-red-500 dark:text-red-500/80">
+            <p className="text-xs text-danger">
               Section: {this.props.label}
             </p>
           )}
 
           {this.state.error && (
-            <p className="max-w-md text-xs text-red-400 dark:text-red-500/60">
+            <p className="max-w-md text-xs text-danger">
               {this.state.error.message}
             </p>
           )}

package/src/components/shared/Fab.tsx

@@ -24,9 +24,18 @@ interface FabCommon {
   /** Accessible name — FABs are icon-only. */
   label: string;
   column: "viewer" | "editor";
-  /** Vertical slot (bottom-*) plus any per-FAB extras. */
+  /** Vertical slot (bottom-*) plus any per-FAB extras. Ignored when `stacked`
+   *  — `FabStack` owns spacing then. */
   className?: string;
   children: ReactNode;
+  /** Renders as a static, non-fixed member of a `FabStack` instead of an
+   *  independently viewport-fixed button: `relative`, no `bottom-*`/`right-*`
+   *  of its own. React context can't cross the viewer page's separate Astro
+   *  islands, so this is a prop, not a stacking context — `FabStack` is
+   *  editor-shell only; the viewer page's FABs never set it. `fab-stacked`
+   *  suppresses the lg+ position rule base.css gives `.fab-container-right`
+   *  (see FabStack), so the two positioning mechanisms don't compound. */
+  stacked?: boolean;
 }
 
 export type FabProps =
@@ -34,12 +43,13 @@ export type FabProps =
   | ({ href?: undefined; ref?: Ref<HTMLButtonElement> } & FabCommon &
       Omit<ComponentPropsWithoutRef<"button">, "children" | "className" | "aria-label" | "type">);
 
-export default function Fab({ label, column, className, children, ...rest }: FabProps) {
+export default function Fab({ label, column, className, children, stacked, ...rest }: FabProps) {
   const classes = cn(
-    "cursor-pointer fixed flex items-center justify-center rounded-full bg-primary text-primary-contrast shadow-lg hover:opacity-90 transition-opacity",
+    "cursor-pointer flex items-center justify-center rounded-full bg-primary text-primary-contrast shadow-lg hover:opacity-90 transition-opacity",
+    stacked ? "relative" : "fixed",
     column === "viewer"
-      ? "z-40 h-12 w-12 right-4 viewer-fab"
-      : "z-50 h-10 w-10 right-4 lg:right-auto fab-container-right",
+      ? cn("h-12 w-12 viewer-fab", !stacked && "z-40 right-4")
+      : cn("h-10 w-10 fab-container-right", stacked ? "fab-stacked" : "z-50 right-4 lg:right-auto"),
     className,
   );
   if (rest.href !== undefined) {

package/src/components/shared/FabStack.tsx

@@ -0,0 +1,28 @@
+import type { ReactNode } from "react";
+
+interface FabStackProps {
+  children: ReactNode;
+}
+
+/** Vertical stack for the /edit FAB column — EditorShell's own FABs
+ *  (mode toggle, doc-edit, BugReportFAB) share this rhythm so they can never
+ *  overlap. ChatWidget's launcher stays independently `fixed` (a React
+ *  context here can't reach it anyway: the viewer page renders each `<Fab>`
+ *  as its own Astro island, and the chat launcher lives inside the
+ *  ChatWidget island).
+ *
+ *  Positioning lives on the container only: `right-4 lg:right-auto` plus
+ *  `fab-container-right`, whose lg+ rule in base.css re-sets `right` to the
+ *  content edge. That rule skips `.fab-stacked`, so stacked children are never
+ *  shifted twice — but it means the container MUST carry the class: without
+ *  it, `lg:right-auto` leaves the fixed column with no horizontal inset at all
+ *  and it falls back to its static position over the page content. Children
+ *  render with `stacked` (relative, no position classes of their own) and
+ *  contribute only spacing via this flex column. */
+export function FabStack({ children }: FabStackProps) {
+  return (
+    <div className="fab-container-right fixed z-50 bottom-16 right-4 lg:right-auto flex flex-col items-end gap-4">
+      {children}
+    </div>
+  );
+}