Fix: empty Storybook args tables for slot parts [WIP]

packages/propel/.storybook/main.ts

@@ -35,8 +35,15 @@ const config: StorybookConfig = {
     reactDocgenTypescriptOptions: {
       shouldExtractLiteralValuesFromEnum: true,
       shouldRemoveUndefinedFromOptional: true,
-      // Only document propel's own props, not the spread DOM / Base UI attributes.
-      propFilter: (prop) => !prop.parent || !prop.parent.fileName.includes("node_modules"),
+      // Only document propel's own props, not the spread DOM / Base UI attributes — plus
+      // `children`, the composition slot. react-docgen attributes `children` to React's
+      // node_modules types, so the base filter would always drop it; yet react-docgen only
+      // emits `children` at all when a part explicitly redeclares it in its own props type
+      // (e.g. the atomic slot parts that take a bare icon / svg / label). Keeping it here
+      // surfaces those opt-in, TSDoc'd `children` slots instead of an empty "couldn't be
+      // auto-generated" args table, without adding a `children` row to every component.
+      propFilter: (prop) =>
+        prop.name === "children" || !prop.parent || !prop.parent.fileName.includes("node_modules"),
     },
   },
   // Storybook runs its own Vite build; add the Tailwind v4 plugin so propel's

packages/propel/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

packages/propel/src/components/accordion/accordion-panel.tsx

@@ -1,19 +1,19 @@
 import {
-  AccordionPanel as AccordionPanelRoot,
+  AccordionPanel as AccordionPanelElement,
   AccordionPanelContent,
-  type AccordionPanelProps as AccordionPanelRootProps,
+  type AccordionPanelProps as AccordionPanelElementProps,
 } from "../../ui/accordion";
 
-export type AccordionPanelProps = AccordionPanelRootProps;
+export type AccordionPanelProps = AccordionPanelElementProps;
 
 /**
  * The ready-made accordion panel: composes the atomic `AccordionPanel` with the
  * `AccordionPanelContent` padding wrapper so content is inset from the trigger's edges.
  */
 export function AccordionPanel({ children, ...props }: AccordionPanelProps) {
   return (
-    <AccordionPanelRoot {...props}>
+    <AccordionPanelElement {...props}>
       <AccordionPanelContent>{children}</AccordionPanelContent>
-    </AccordionPanelRoot>
+    </AccordionPanelElement>
   );
 }

packages/propel/src/components/accordion/accordion-trigger.tsx

@@ -2,14 +2,14 @@ import { ChevronDown } from "lucide-react";
 import type * as React from "react";
 
 import {
-  AccordionTrigger as AccordionTriggerRoot,
-  type AccordionTriggerProps as AccordionTriggerRootProps,
+  AccordionTrigger as AccordionTriggerElement,
+  type AccordionTriggerProps as AccordionTriggerElementProps,
   AccordionTriggerIcon,
   AccordionTriggerIndicator,
   AccordionTriggerTitle,
 } from "../../ui/accordion";
 
-export type AccordionTriggerProps = AccordionTriggerRootProps & {
+export type AccordionTriggerProps = AccordionTriggerElementProps & {
   /**
    * Node rendered before the label (inline-start), matching the Figma header icon. Sized to the
    * trigger's `--node-size`. Decorative, kept out of the name.
@@ -24,12 +24,12 @@ export type AccordionTriggerProps = AccordionTriggerRootProps & {
  */
 export function AccordionTrigger({ inlineStartNode, children, ...props }: AccordionTriggerProps) {
   return (
-    <AccordionTriggerRoot {...props}>
+    <AccordionTriggerElement {...props}>
       {inlineStartNode ? <AccordionTriggerIcon>{inlineStartNode}</AccordionTriggerIcon> : null}
       <AccordionTriggerTitle>{children}</AccordionTriggerTitle>
       <AccordionTriggerIndicator>
         <ChevronDown />
       </AccordionTriggerIndicator>
-    </AccordionTriggerRoot>
+    </AccordionTriggerElement>
   );
 }

packages/propel/src/components/accordion/index.tsx

@@ -1,5 +1,5 @@
-export { AccordionPanel, type AccordionPanelProps } from "./accordion-panel";
-export { AccordionTrigger, type AccordionTriggerProps } from "./accordion-trigger";
+export * from "./accordion-panel";
+export * from "./accordion-trigger";
 // Re-export the atomic structural parts so a full accordion is importable from this convenience.
 export {
   Accordion,

packages/propel/src/components/alert-dialog/alert-dialog.stories.tsx

@@ -45,7 +45,13 @@ type Story = StoryObj<typeof meta>;
 export const Default: Story = {
   render: () => (
     <AlertDialog>
-      <Button variant="primary" tone="danger" magnitude="xl" render={<AlertDialogTrigger />}>
+      <Button
+        sizing="hug"
+        prominence="primary"
+        tone="danger"
+        magnitude="xl"
+        render={<AlertDialogTrigger />}
+      >
         Delete project
       </Button>
       <AlertDialogContent>
@@ -62,10 +68,22 @@ export const Default: Story = {
           </AlertDialogIntro>
         </AlertDialogHeader>
         <AlertDialogActions>
-          <Button variant="secondary" tone="neutral" magnitude="xl" render={<AlertDialogClose />}>
+          <Button
+            sizing="hug"
+            prominence="secondary"
+            tone="neutral"
+            magnitude="xl"
+            render={<AlertDialogClose />}
+          >
             Cancel
           </Button>
-          <Button variant="primary" tone="danger" magnitude="xl" render={<AlertDialogClose />}>
+          <Button
+            sizing="hug"
+            prominence="primary"
+            tone="danger"
+            magnitude="xl"
+            render={<AlertDialogClose />}
+          >
             Delete
           </Button>
         </AlertDialogActions>

packages/propel/src/components/alert-dialog/index.tsx

@@ -1,4 +1,4 @@
-export { AlertDialogContent, type AlertDialogContentProps } from "./alert-dialog-content";
+export * from "./alert-dialog-content";
 // Re-export the atomic parts so a full alert dialog can be assembled from one entry.
 export {
   AlertDialog,

packages/propel/src/components/anchor-button/anchor-button.stories.tsx

@@ -0,0 +1,60 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { ArrowRight, Plus } from "lucide-react";
+import { expect } from "storybook/test";
+
+import { iconControl } from "../../storybook/icon-control";
+import { AnchorButton, AnchorButtonIcon, AnchorButtonLabel, AnchorButtonSpinner } from "./index";
+
+// The ready-made button-looking link: a navigation `<a>` with the control chrome plus optional
+// inline-start/inline-end nodes beside the label. Same surface as the ready-made `Button`, but it
+// navigates (`href`) instead of acting.
+const meta = {
+  title: "Components/AnchorButton",
+  component: AnchorButton,
+  subcomponents: { AnchorButtonIcon, AnchorButtonLabel, AnchorButtonSpinner },
+  argTypes: { inlineStartNode: iconControl, inlineEndNode: iconControl },
+  args: {
+    children: "Link",
+    href: "#",
+    prominence: "primary",
+    tone: "neutral",
+    magnitude: "md",
+    sizing: "hug",
+  },
+} satisfies Meta<typeof AnchorButton>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+/** Inline-start and inline-end nodes sit beside the label and are decorative. */
+export const WithIcons: Story = {
+  parameters: { controls: { disable: true } },
+  render: (args) => (
+    <div className="flex items-center gap-3">
+      <AnchorButton {...args} inlineStartNode={<Plus />}>
+        New page
+      </AnchorButton>
+      <AnchorButton {...args} prominence="secondary" inlineEndNode={<ArrowRight />}>
+        Learn more
+      </AnchorButton>
+    </div>
+  ),
+};
+
+/**
+ * `loading` shows a spinner + sets `aria-busy` while a navigation is pending (e.g. a router's
+ * pending state).
+ */
+export const Loading: Story = { args: { loading: true } };
+
+/** It renders a real `<a>` carrying the given `href`, so it navigates rather than acts. */
+export const RendersAnchor: Story = {
+  tags: ["!dev", "!autodocs", "!manifest"],
+  args: { href: "https://example.com" },
+  play: async ({ canvas }) => {
+    const link = canvas.getByRole("link", { name: "Link" });
+    await expect(link).toHaveAttribute("href", "https://example.com");
+  },
+};

packages/propel/src/components/anchor-button/anchor-button.tsx

@@ -0,0 +1,50 @@
+import { LoaderCircle } from "lucide-react";
+import type * as React from "react";
+
+import {
+  AnchorButton as AnchorButtonElement,
+  AnchorButtonIcon,
+  AnchorButtonLabel,
+  type AnchorButtonProps as AnchorButtonElementProps,
+  AnchorButtonSpinner,
+} from "../../ui/anchor-button";
+
+export type AnchorButtonProps = AnchorButtonElementProps & {
+  /** Node before the label (inline-start), sized to `--node-size`. Decorative. */
+  inlineStartNode?: React.ReactNode;
+  /** Node after the label (inline-end), sized to `--node-size`. Decorative. */
+  inlineEndNode?: React.ReactNode;
+  /**
+   * Shows a spinner in place of the inline-start node and sets `aria-busy` while a navigation is
+   * pending — drive it from your router's pending state (e.g. React Router's `useNavigation`),
+   * since a link's destination can load before the page changes.
+   */
+  loading?: boolean;
+};
+
+/**
+ * The ready-made `AnchorButton`: a button-looking navigation link that composes the atomic
+ * `AnchorButton` with an optional `inlineStartNode`/`inlineEndNode` and a `loading` spinner for
+ * pending navigations. Content — `children`, the inline nodes, `loading` — is not a variant.
+ */
+export function AnchorButton({
+  inlineStartNode,
+  inlineEndNode,
+  loading = false,
+  children,
+  ...props
+}: AnchorButtonProps) {
+  return (
+    <AnchorButtonElement aria-busy={loading ? true : undefined} {...props}>
+      {loading ? (
+        <AnchorButtonSpinner>
+          <LoaderCircle />
+        </AnchorButtonSpinner>
+      ) : inlineStartNode ? (
+        <AnchorButtonIcon>{inlineStartNode}</AnchorButtonIcon>
+      ) : null}
+      <AnchorButtonLabel>{children}</AnchorButtonLabel>
+      {!loading && inlineEndNode ? <AnchorButtonIcon>{inlineEndNode}</AnchorButtonIcon> : null}
+    </AnchorButtonElement>
+  );
+}

packages/propel/src/components/anchor-button/index.tsx

@@ -0,0 +1,13 @@
+export * from "./anchor-button";
+export {
+  AnchorButtonIcon,
+  type AnchorButtonIconProps,
+  AnchorButtonLabel,
+  type AnchorButtonLabelProps,
+  AnchorButtonSpinner,
+  type AnchorButtonSpinnerProps,
+  type AnchorButtonMagnitude,
+  type AnchorButtonProminence,
+  type AnchorButtonSizing,
+  type AnchorButtonTone,
+} from "../../ui/anchor-button";

packages/propel/src/components/anchor/anchor.stories.tsx

@@ -0,0 +1,58 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect } from "storybook/test";
+
+import { Anchor, type AnchorMagnitude, type AnchorProminence } from "./index";
+
+const PROMINENCES: AnchorProminence[] = ["primary", "secondary"];
+const MAGNITUDES: AnchorMagnitude[] = ["sm", "md", "lg", "xl"];
+
+// The inline text link. For a button-styled nav link use `AnchorButton`; for a link-styled action
+// use `ButtonAnchor`.
+const meta = {
+  title: "Components/Anchor",
+  component: Anchor,
+  args: { children: "Anchor", href: "#", prominence: "primary", magnitude: "md" },
+} satisfies Meta<typeof Anchor>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+/** `prominence`: `primary` is the blue link; `secondary` the muted gray inline link. */
+export const Prominences: Story = {
+  argTypes: { prominence: { control: false }, children: { control: false } },
+  render: (args) => (
+    <div className="flex items-center gap-4">
+      {PROMINENCES.map((prominence) => (
+        <Anchor key={prominence} {...args} prominence={prominence}>
+          {prominence} link
+        </Anchor>
+      ))}
+    </div>
+  ),
+};
+
+/** Text sizes (Figma S/Base/L/XL map to sm/md/lg/xl). */
+export const Magnitudes: Story = {
+  argTypes: { magnitude: { control: false }, children: { control: false } },
+  render: (args) => (
+    <div className="flex items-center gap-4">
+      {MAGNITUDES.map((magnitude) => (
+        <Anchor key={magnitude} {...args} magnitude={magnitude}>
+          {magnitude}
+        </Anchor>
+      ))}
+    </div>
+  ),
+};
+
+/** It renders a real `<a>` carrying the given `href`. */
+export const RendersAnchor: Story = {
+  tags: ["!dev", "!autodocs", "!manifest"],
+  args: { href: "https://example.com" },
+  play: async ({ canvas }) => {
+    const link = canvas.getByRole("link", { name: "Anchor" });
+    await expect(link).toHaveAttribute("href", "https://example.com");
+  },
+};

packages/propel/src/components/anchor/index.tsx

@@ -0,0 +1,3 @@
+// Ready-made 1:1 re-export of the ui primitive. Drop to `@plane/propel/ui/anchor` only for the
+// lower-level parts. (`Anchor` is a single styled `<a>`, so there is nothing extra to compose.)
+export * from "../../ui/anchor";

packages/propel/src/components/autocomplete/index.tsx

@@ -1,4 +1,4 @@
-export { AutocompleteContent, type AutocompleteContentProps } from "./autocomplete-content";
+export * from "./autocomplete-content";
 // Re-export the atomic autocomplete parts so a full autocomplete can be assembled from one entry.
 export {
   Autocomplete,

packages/propel/src/components/avatar-group/avatar-group.tsx

@@ -0,0 +1,31 @@
+import type * as React from "react";
+
+import { type AvatarMagnitude } from "../../ui/avatar";
+import {
+  AvatarGroup as AvatarGroupElement,
+  type AvatarGroupProps as AvatarGroupElementProps,
+} from "../../ui/avatar-group";
+import { AvatarGroupContext } from "../avatar/avatar-group-context";
+
+// Figma's "Avatar Groups" component only defines three sizes (Small/Base/Large = 16/20/24px), so
+// groups are limited to the matching magnitudes — narrower than a standalone Avatar's full scale.
+export type AvatarGroupMagnitude = Extract<AvatarMagnitude, "2xs" | "xs" | "sm">;
+
+export type AvatarGroupProps = AvatarGroupElementProps & {
+  /** Shared size for every avatar in the group; an avatar's own `magnitude` overrides it. */
+  magnitude: AvatarGroupMagnitude;
+  children?: React.ReactNode;
+};
+
+/**
+ * The ready-made overlapping avatar stack: shares `magnitude` with every `Avatar` inside via
+ * context (an avatar's own `magnitude` still wins), composed around the styled `ui/avatar-group`
+ * container. Each `Avatar`'s own `border-subtle` is the single ring that separates them.
+ */
+export function AvatarGroup({ magnitude, children, ...props }: AvatarGroupProps) {
+  return (
+    <AvatarGroupContext.Provider value={magnitude}>
+      <AvatarGroupElement {...props}>{children}</AvatarGroupElement>
+    </AvatarGroupContext.Provider>
+  );
+}

packages/propel/src/components/avatar-group/index.tsx

@@ -1,3 +1 @@
-// Ready-made 1:1 re-export of the ui primitive. Drop down to `@plane/propel/ui/avatar-group` only
-// when you need the lower-level parts.
-export * from "../../ui/avatar-group";
+export * from "./avatar-group";

packages/propel/src/components/avatar/avatar-group-context.ts

@@ -0,0 +1,10 @@
+import * as React from "react";
+
+import type { AvatarMagnitude } from "../../ui/avatar";
+
+/**
+ * Set by the components `AvatarGroup` so every `Avatar` inside it shares one `magnitude` (an
+ * avatar's own `magnitude` still wins). Lives in the components tier: a context is cross-tree
+ * coordination — composition — not a single-element `ui` concern.
+ */
+export const AvatarGroupContext = React.createContext<AvatarMagnitude | undefined>(undefined);