Sep 20, 2024 · Sep 12, 2024 · Sep 12, 2024 · Sep 12, 2024 · Sep 12, 2024 · Sep 12, 2024
diff --git a/.vscode/settings.json b/.vscode/settings.json
 "stretchr",
 "STTY",
 "stuntest",
 "subpage",
 "tailbroker",
 "tailcfg",
 "tailexchange",
diff --git a/site/src/components/FeatureStageBadge/FeatureStageBadge.stories.tsx b/site/src/components/FeatureStageBadge/FeatureStageBadge.stories.tsx
 import type { Meta, StoryObj } from "@storybook/react";
 import { FeatureStageBadge } from "./FeatureStageBadge";

 const meta: Meta<typeof FeatureStageBadge> = {
 title: "components/FeatureStageBadge",
 component: FeatureStageBadge,
 args: {
 contentType: "beta",
 },
 };

 export default meta;
 type Story = StoryObj<typeof FeatureStageBadge>;

 export const MediumBeta: Story = {
 args: {
 size: "md",
 },
 };

 export const SmallBeta: Story = {
 args: {
 size: "sm",
 },
 };

 export const LargeBeta: Story = {
 args: {
 size: "lg",
 },
 };

 export const MediumExperimental: Story = {
 args: {
 size: "md",
 contentType: "experimental",
 },
 };
diff --git a/site/src/components/FeatureStageBadge/FeatureStageBadge.tsx b/site/src/components/FeatureStageBadge/FeatureStageBadge.tsx
 import type { Interpolation, Theme } from "@emotion/react";
 import Link from "@mui/material/Link";
 import { visuallyHidden } from "@mui/utils";
 import { HelpTooltipContent } from "components/HelpTooltip/HelpTooltip";
 import { Popover, PopoverTrigger } from "components/Popover/Popover";
 import type { FC, HTMLAttributes, ReactNode } from "react";
 import { docs } from "utils/docs";

 /**
 * All types of feature that we are currently supporting. Defined as record to
 * ensure that we can't accidentally make typos when writing the badge text.
 */
 const featureStageBadgeTypes = {
 beta: "beta",
 experimental: "experimental",
 } as const satisfies Record<string, ReactNode>;

 type FeatureStageBadgeProps = Readonly<
 Omit<HTMLAttributes<HTMLSpanElement>, "children"> & {
 contentType: keyof typeof featureStageBadgeTypes;
 size?: "sm" | "md" | "lg";
 }
 >;

 export const FeatureStageBadge: FC<FeatureStageBadgeProps> = ({
 contentType,
 size = "md",
 ...delegatedProps
 }) => {
 return (
 <Popover mode="hover">
 <PopoverTrigger>
 {({ isOpen }) => (
 <span
 css={[
 styles.badge,
 size === "sm" && styles.badgeSmallText,
 size === "lg" && styles.badgeLargeText,
 isOpen && styles.badgeHover,
 ]}
 {...delegatedProps}
 >
 <span style={visuallyHidden}> (This is a</span>
 {featureStageBadgeTypes[contentType]}
 <span style={visuallyHidden}> feature)</span>
 </span>
 )}
 </PopoverTrigger>

 <HelpTooltipContent
 anchorOrigin={{ vertical: "bottom", horizontal: "center" }}
 transformOrigin={{ vertical: "top", horizontal: "center" }}
 >
 <p css={styles.tooltipDescription}>
 This feature has not yet reached general availability (GA).
 </p>

 <Link
 href={docs("/contributing/feature-stages")}
 target="_blank"
 rel="noreferrer"
 css={styles.tooltipLink}
 >
 Learn about feature stages
 <span style={visuallyHidden}> (link opens in new tab)</span>
 </Link>
 </HelpTooltipContent>
 </Popover>
 );
 };

 const styles = {
 badge: (theme) => ({
 // Base type is based on a span so that the element can be placed inside
 // more types of HTML elements without creating invalid markdown, but we
 // still want the default display behavior to be div-like
 display: "block",
 maxWidth: "fit-content",

 // Base style assumes that medium badges will be the default
 fontSize: "0.75rem",

 cursor: "default",
 flexShrink: 0,
 padding: "4px 8px",
 lineHeight: 1,
 whiteSpace: "nowrap",
 border: `1px solid ${theme.branding.featureStage.border}`,
 color: theme.branding.featureStage.text,
 backgroundColor: theme.branding.featureStage.background,
 borderRadius: "6px",
 transition:
 "color 0.2s ease-in-out, border-color 0.2s ease-in-out, background-color 0.2s ease-in-out",
 }),

 badgeHover: (theme) => ({
 color: theme.branding.featureStage.hover.text,
 borderColor: theme.branding.featureStage.hover.border,
 backgroundColor: theme.branding.featureStage.hover.background,
 }),

 badgeLargeText: {
 fontSize: "1rem",
 },

 badgeSmallText: {
 // Have to beef up font weight so that the letters still maintain the
 // same relative thickness as all our other main UI text
 fontWeight: 500,
 fontSize: "0.625rem",
 },

 tooltipTitle: (theme) => ({
 color: theme.palette.text.primary,
 fontWeight: 600,
 fontFamily: "inherit",
 fontSize: 18,
 margin: 0,
 lineHeight: 1,
 paddingBottom: "8px",
 }),

 tooltipDescription: {
 margin: 0,
 lineHeight: 1.4,
 paddingBottom: "8px",
 },

 tooltipLink: {
 fontWeight: 600,
 lineHeight: 1.2,
 },
 } as const satisfies Record<string, Interpolation<Theme>>;
diff --git a/site/src/components/Form/Form.tsx b/site/src/components/Form/Form.tsx
 formSectionInfoTitle: (theme) => ({
 fontSize: 20,
 color: theme.palette.text.primary,
 fontWeight:400,
 fontWeight:500,
 margin: 0,
 marginBottom: 8,
 display: "flex",
diff --git a/site/src/components/Popover/Popover.tsx b/site/src/components/Popover/Popover.tsx
 import MuiPopover, {
 type PopoverProps as MuiPopoverProps,
 // biome-ignore lint/nursery/noRestrictedImports:Used asbase component
 // biome-ignore lint/nursery/noRestrictedImports:This is thebase component that our custom popover is based on
 } from "@mui/material/Popover";
 import {
 type FC,
 type HTMLAttributes,
 type PointerEvent,
 type PointerEventHandler,
 type ReactElement,
 type ReactNode,
 type RefObject,
 cloneElement,
 createContext,
 useContext,
 useEffect,
 useId,
 useRef,
 useState,

 type TriggerRef = RefObject<HTMLElement>;

 type TriggerElement = ReactElement<{
 ref: TriggerRef;
 onClick?: () => void;
 }>;
 // Have to append ReactNode type to satisfy React's cloneElement function. It
 // has absolutely no bearing on what happens at runtime
 type TriggerElement = ReactNode &
 ReactElement<{
 ref: TriggerRef;
 onClick?: () => void;
 }>;

 type PopoverContextValue = {
 id: string;
 const [uncontrolledOpen, setUncontrolledOpen] = useState(false);
 const triggerRef: TriggerRef = useRef(null);

 // Helps makes sure that popovers close properly when the user switches to
 // a different tab. This won't help with controlled instances of the
 // component, but this is basically the most we can do from here
 useEffect(() => {
 const closeOnTabSwitch = () => setUncontrolledOpen(false);
 window.addEventListener("blur", closeOnTabSwitch);
 return () => window.removeEventListener("blur", closeOnTabSwitch);
 }, []);

 const value: PopoverContextValue = {
 triggerRef,
 id: `${hookId}-popover`,
 return context;
 };

 export const PopoverTrigger = (
 props: HTMLAttributes<HTMLElement> & {
 children: TriggerElement;
 },
 ) => {
 type PopoverTriggerRenderProps = Readonly<{
 isOpen: boolean;
 }>;

 type PopoverTriggerProps = Readonly<
 Omit<HTMLAttributes<HTMLElement>, "children"> & {
 children:
 | TriggerElement
 | ((props: PopoverTriggerRenderProps) => TriggerElement);
 }
 >;

 export const PopoverTrigger: FC<PopoverTriggerProps> = (props) => {
 const popover = usePopover();
 const { children, ...elementProps } = props;
 const { children, onClick, onPointerEnter, onPointerLeave, ...elementProps } =
 props;

 const clickProps = {
 onClick: () => {
 onClick: (event: PointerEvent<HTMLElement>) => {
 popover.setOpen(true);
 onClick?.(event);
 },
 };

 const hoverProps = {
 onPointerEnter: () => {
 onPointerEnter: (event: PointerEvent<HTMLElement>) => {
 popover.setOpen(true);
 onPointerEnter?.(event);
 },
 onPointerLeave: () => {
 onPointerLeave: (event: PointerEvent<HTMLElement>) => {
 popover.setOpen(false);
 onPointerLeave?.(event);
 },
 };

 return cloneElement(props.children, {
 const evaluatedChildren =
 typeof children === "function"
 ? children({ isOpen: popover.open })
 : children;

 return cloneElement(evaluatedChildren, {
 ...elementProps,
 ...(popover.mode === "click" ? clickProps : hoverProps),
 "aria-haspopup": true,

 export const PopoverContent: FC<PopoverContentProps> = ({
 horizontal = "left",
 onPointerEnter,
 onPointerLeave,
 ...popoverProps
 }) => {
 const popover = usePopover();
 },
 }}
 {...horizontalProps(horizontal)}
 {...modeProps(popover)}
 {...modeProps(popover, onPointerEnter, onPointerLeave)}
 {...popoverProps}
 id={popover.id}
 open={popover.open}
 );
 };

 const modeProps = (popover: PopoverContextValue) => {
 const modeProps = (
 popover: PopoverContextValue,
 externalOnPointerEnter: PointerEventHandler<HTMLDivElement> | undefined,
 externalOnPointerLeave: PointerEventHandler<HTMLDivElement> | undefined,
 ) => {
 if (popover.mode === "hover") {
 return {
 onPointerEnter: () => {
 onPointerEnter: (event: PointerEvent<HTMLDivElement>) => {
 popover.setOpen(true);
 externalOnPointerEnter?.(event);
 },
 onPointerLeave: () => {
 onPointerLeave: (event: PointerEvent<HTMLDivElement>) => {
 popover.setOpen(false);
 externalOnPointerLeave?.(event);
 },
 };
 }
Original file line number	Diff line number	Diff line change
Expand Up		@@ -120,6 +120,7 @@
		"stretchr",
		"STTY",
		"stuntest",
		"subpage",
aslilac marked this conversation as resolved. Show resolvedHide resolved
		"tailbroker",
		"tailcfg",
		"tailexchange",
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,38 @@
		import type { Meta, StoryObj } from "@storybook/react";
		import { FeatureStageBadge } from "./FeatureStageBadge";

		const meta: Meta<typeof FeatureStageBadge> = {
		title: "components/FeatureStageBadge",
		component: FeatureStageBadge,
		args: {
		contentType: "beta",
		},
		};

		export default meta;
		type Story = StoryObj<typeof FeatureStageBadge>;

		export const MediumBeta: Story = {
		args: {
		size: "md",
		},
		};

		export const SmallBeta: Story = {
		args: {
		size: "sm",
		},
		};

		export const LargeBeta: Story = {
		args: {
		size: "lg",
		},
		};

		export const MediumExperimental: Story = {
		args: {
		size: "md",
		contentType: "experimental",
		},
		};
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,133 @@
		import type { Interpolation, Theme } from "@emotion/react";
		import Link from "@mui/material/Link";
		import { visuallyHidden } from "@mui/utils";
		import { HelpTooltipContent } from "components/HelpTooltip/HelpTooltip";
		import { Popover, PopoverTrigger } from "components/Popover/Popover";
		import type { FC, HTMLAttributes, ReactNode } from "react";
		import { docs } from "utils/docs";

		/**
		* All types of feature that we are currently supporting. Defined as record to
		* ensure that we can't accidentally make typos when writing the badge text.
		*/
		const featureStageBadgeTypes = {
		beta: "beta",
		experimental: "experimental",
		} as const satisfies Record<string, ReactNode>;

		type FeatureStageBadgeProps = Readonly<
		Omit<HTMLAttributes<HTMLSpanElement>, "children"> & {
		contentType: keyof typeof featureStageBadgeTypes;
		size?: "sm" \| "md" \| "lg";
		}
		>;

		export const FeatureStageBadge: FC<FeatureStageBadgeProps> = ({
		contentType,
		size = "md",
		...delegatedProps
		}) => {
		return (
		<Popover mode="hover">
		<PopoverTrigger>
		{({ isOpen }) => (
		<span
		css={[
		styles.badge,
		size === "sm" && styles.badgeSmallText,
		size === "lg" && styles.badgeLargeText,
		isOpen && styles.badgeHover,
		]}
		{...delegatedProps}
		>
		<span style={visuallyHidden}> (This is a</span>
		{featureStageBadgeTypes[contentType]}
		<span style={visuallyHidden}> feature)</span>
		</span>
		)}
		</PopoverTrigger>

		<HelpTooltipContent
		anchorOrigin={{ vertical: "bottom", horizontal: "center" }}
		transformOrigin={{ vertical: "top", horizontal: "center" }}
		>
		<p css={styles.tooltipDescription}>
		This feature has not yet reached general availability (GA).
		</p>

		<Link
		href={docs("/contributing/feature-stages")}
		target="_blank"
		rel="noreferrer"
		css={styles.tooltipLink}
		>
		Learn about feature stages
		<span style={visuallyHidden}> (link opens in new tab)</span>
		</Link>
		</HelpTooltipContent>
		</Popover>
		);
		};

		const styles = {
Copy link Member aslilacSep 20, 2024 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. I think we generally define`styles` below the component
		badge: (theme) => ({
		// Base type is based on a span so that the element can be placed inside
		// more types of HTML elements without creating invalid markdown, but we
		// still want the default display behavior to be div-like
		display: "block",
		maxWidth: "fit-content",

		// Base style assumes that medium badges will be the default
		fontSize: "0.75rem",

		cursor: "default",
		flexShrink: 0,
		padding: "4px 8px",
		lineHeight: 1,
		whiteSpace: "nowrap",
		border: `1px solid ${theme.branding.featureStage.border}`,
		color: theme.branding.featureStage.text,
		backgroundColor: theme.branding.featureStage.background,
		borderRadius: "6px",
		transition:
		"color 0.2s ease-in-out, border-color 0.2s ease-in-out, background-color 0.2s ease-in-out",
		}),

		badgeHover: (theme) => ({
		color: theme.branding.featureStage.hover.text,
		borderColor: theme.branding.featureStage.hover.border,
		backgroundColor: theme.branding.featureStage.hover.background,
		}),

		badgeLargeText: {
		fontSize: "1rem",
		},

		badgeSmallText: {
		// Have to beef up font weight so that the letters still maintain the
		// same relative thickness as all our other main UI text
		fontWeight: 500,
		fontSize: "0.625rem",
		},

		tooltipTitle: (theme) => ({
		color: theme.palette.text.primary,
		fontWeight: 600,
		fontFamily: "inherit",
		fontSize: 18,
		margin: 0,
		lineHeight: 1,
		paddingBottom: "8px",
		}),

		tooltipDescription: {
		margin: 0,
		lineHeight: 1.4,
		paddingBottom: "8px",
		},

		tooltipLink: {
		fontWeight: 600,
		lineHeight: 1.2,
		},
		} as const satisfies Record<string, Interpolation<Theme>>;
Original file line number	Diff line number	Diff line change
Expand Up		@@ -170,7 +170,7 @@ const styles = {
		formSectionInfoTitle: (theme) => ({
		fontSize: 20,
		color: theme.palette.text.primary,
		fontWeight:400,
		fontWeight:500,
		margin: 0,
		marginBottom: 8,
		display: "flex",
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,16 +1,19 @@
		import MuiPopover, {
		type PopoverProps as MuiPopoverProps,
		// biome-ignore lint/nursery/noRestrictedImports:Used asbase component
		// biome-ignore lint/nursery/noRestrictedImports:This is thebase component that our custom popover is based on
Copy link MemberAuthor ParkreinerSep 18, 2024 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. I might have Biome configured wrong because my Biome plugin is flagging all of these comments as not doing anything Accidentally removed this at first, but that's definitely a me problem, right? Copy link Member aslilacSep 18, 2024 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. I think it doesn't like that our biome.json config is in the site/ directory 🙄 I hate that extensions never bother to handle subdirectories well.
		} from "@mui/material/Popover";
		import {
		type FC,
		type HTMLAttributes,
		type PointerEvent,
		type PointerEventHandler,
		type ReactElement,
		type ReactNode,
		type RefObject,
		cloneElement,
		createContext,
		useContext,
		useEffect,
		useId,
		useRef,
		useState,
Expand All		@@ -20,10 +23,13 @@ type TriggerMode = "hover" \| "click";

		type TriggerRef = RefObject<HTMLElement>;

		type TriggerElement = ReactElement<{
		ref: TriggerRef;
		onClick?: () => void;
		}>;
		// Have to append ReactNode type to satisfy React's cloneElement function. It
		// has absolutely no bearing on what happens at runtime
		type TriggerElement = ReactNode &
		ReactElement<{
		ref: TriggerRef;
		onClick?: () => void;
		}>;

		type PopoverContextValue = {
		id: string;
Expand DownExpand Up		@@ -61,6 +67,15 @@ export const Popover: FC<PopoverProps> = (props) => {
		const [uncontrolledOpen, setUncontrolledOpen] = useState(false);
		const triggerRef: TriggerRef = useRef(null);

		// Helps makes sure that popovers close properly when the user switches to
		// a different tab. This won't help with controlled instances of the
		// component, but this is basically the most we can do from here
		useEffect(() => {
		const closeOnTabSwitch = () => setUncontrolledOpen(false);
		window.addEventListener("blur", closeOnTabSwitch);
		return () => window.removeEventListener("blur", closeOnTabSwitch);
		}, []);

		const value: PopoverContextValue = {
		triggerRef,
		id: `${hookId}-popover`,
Expand All		@@ -86,30 +101,47 @@ export const usePopover = () => {
		return context;
		};

		export const PopoverTrigger = (
		props: HTMLAttributes<HTMLElement> & {
		children: TriggerElement;
		},
		) => {
		type PopoverTriggerRenderProps = Readonly<{
		isOpen: boolean;
		}>;

		type PopoverTriggerProps = Readonly<
		Omit<HTMLAttributes<HTMLElement>, "children"> & {
		children:
		\| TriggerElement
		\| ((props: PopoverTriggerRenderProps) => TriggerElement);
		}
		>;

		export const PopoverTrigger: FC<PopoverTriggerProps> = (props) => {
		const popover = usePopover();
		const { children, ...elementProps } = props;
		const { children, onClick, onPointerEnter, onPointerLeave, ...elementProps } =
		props;

		const clickProps = {
		onClick: () => {
		onClick: (event: PointerEvent<HTMLElement>) => {
		popover.setOpen(true);
		onClick?.(event);
		},
		};

		const hoverProps = {
		onPointerEnter: () => {
		onPointerEnter: (event: PointerEvent<HTMLElement>) => {
		popover.setOpen(true);
		onPointerEnter?.(event);
		},
		onPointerLeave: () => {
		onPointerLeave: (event: PointerEvent<HTMLElement>) => {
		popover.setOpen(false);
		onPointerLeave?.(event);
		},
		};

		return cloneElement(props.children, {
		const evaluatedChildren =
		typeof children === "function"
		? children({ isOpen: popover.open })
		: children;

		return cloneElement(evaluatedChildren, {
		...elementProps,
		...(popover.mode === "click" ? clickProps : hoverProps),
		"aria-haspopup": true,
Expand All		@@ -130,6 +162,8 @@ export type PopoverContentProps = Omit<

		export const PopoverContent: FC<PopoverContentProps> = ({
		horizontal = "left",
		onPointerEnter,
		onPointerLeave,
		...popoverProps
		}) => {
		const popover = usePopover();
Expand All		@@ -152,7 +186,7 @@ export const PopoverContent: FC<PopoverContentProps> = ({
		},
		}}
		{...horizontalProps(horizontal)}
		{...modeProps(popover)}
		{...modeProps(popover, onPointerEnter, onPointerLeave)}
		{...popoverProps}
		id={popover.id}
		open={popover.open}
Expand All		@@ -162,14 +196,20 @@ export const PopoverContent: FC<PopoverContentProps> = ({
		);
		};

		const modeProps = (popover: PopoverContextValue) => {
		const modeProps = (
		popover: PopoverContextValue,
		externalOnPointerEnter: PointerEventHandler<HTMLDivElement> \| undefined,
		externalOnPointerLeave: PointerEventHandler<HTMLDivElement> \| undefined,
		) => {
		if (popover.mode === "hover") {
		return {
		onPointerEnter: () => {
		onPointerEnter: (event: PointerEvent<HTMLDivElement>) => {
		popover.setOpen(true);
		externalOnPointerEnter?.(event);
		},
		onPointerLeave: () => {
		onPointerLeave: (event: PointerEvent<HTMLDivElement>) => {
		popover.setOpen(false);
		externalOnPointerLeave?.(event);
		},
		};
		}
Expand Down