Clean up how we use links

[rchlfryn]

Description

This PR cleans up for we use Button and CMSLink components. We currently use buttons in 3 different ways:

1. CMSLink - a guided way for a user to choose a link form a collection. Looks like a button but is rendered as an a tag
2. Link + Button - a link to another page or action
3. Button - not a link but performs an action

---

From the linked issue:

This issue should consider the best approach to using links with button styling that also capture events.

I assume the second part of this is referring to Posthog events. All link clicks are autocaptured by posthog.

Related Issues

Resolves #685
Resolves #753

Key Changes

• Add ButtonLink component and consolidates CMSLink to ButtonLink since we were repeating the components pattern
• Removed unused button variants destructive and link
• Updated EventTable and EventPreview to use proper Button component instead of incorrectly used CMSLink
• Adds clearIrrelevantLinkValues to linkField
• Refactors linkToPageOrPost to linkField
  • Needed to keep linkToPageOrPost for quickLinks config since the type is array instead of group
• Clean up defaultLexical url validation
• Updated coding guide

How to test

There should be no visual differences

Migration

Rename button_appearance to button_variant

Future enhancements / Questions

We could use linkField in navLink, since the configs are identical. Using linkField will change newTab to be the second column which will cause a migration that will create a new table and drop the old one which seems invasive for the change. Do we want to do this?

[github-actions]

Preview deployment: https://link-cleanup.preview.avy-fx.org

[busbyk]

Left some comments and had an idea: #900

Psyched to get this consolidated/consistent.

[busbyk]

I'm not clear on the intent for Button, ButtonLink, and CMSLink from these docs / from usage in general.

The use of Button is clear - it's just a button that's not a link. Although I'm surprised that PostHog autocaptures clicks on buttons that aren't wrapped in links / have a child. Is that true?

The difference in usage of ButtonLink and CMSLink is fuzzy. They both render a Button component with a Link inside it with pretty much the same props.

The only things CMSLink does differently is:

• Accepts an internal reference (a Payload document from pages, posts, or builtInPages) and uses handleReferenceURL to determine the internal url
• Uses a custom PostHog event capture which includes the tenant

I get that ButtonLink is specifically for external URLs but I'm definitely feeling like these could just be a single component.

I wonder if we wouldn't want that custom PostHog event capture with tenant context on external links too.

Using CMSLink (the naming specifically being the issue) is confusing for explicitly external links but I think passing a reference (i.e. Payload document) into a ButtonLink component wouldn't be too confusing. Maybe reference isn't the best prop name but 🤷.

I think it would be clearer to just have a single ButtonLink which should be used for all links (internal and external) that should be styled as buttons. If you want a link that's not styled as a button you can use a pattern similar to ImageLinkGridBlock where you use handleReferenceURL and Link.

I don't think we even really need to call out the usage of Button here necessarily except maybe to say: don't use an onClick handler to programmatically navigate unless there's a use case that makes sense but...that could go without saying idk.

Thoughts?

[rchlfryn]

Great thoughts, I consolidated CMSLink into Button link in c452956

The use of Button is clear - it's just a button that's not a link. Although I'm surprised that PostHog autocaptures clicks on buttons that aren't wrapped in links / have a child. Is that true?

Yes that is true - check out this dashboard

The only things CMSLink does differently is:

• Accepts an internal reference (a Payload document from pages, posts, or builtInPages) and uses handleReferenceURL to determine the internal url
• Uses a custom PostHog event capture which includes the tenant
  I get that ButtonLink is specifically for external URLs but I'm definitely feeling like these could just be a single component.

I was trying for CMSLink to handle anything that had an admin interface and ButtonLink was anything we linked to in the code, but I forgot CMSLink can have an external URL. As I mentioned everything has been consolidated in c452956

Using CMSLink (the naming specifically being the issue) is confusing for explicitly external links but I think passing a reference (i.e. Payload document) into a ButtonLink component wouldn't be too confusing. Maybe reference isn't the best prop name but 🤷.

LinkFeature uses doc. Take a look and let me know if we should rename the prop.

I don't think we even really need to call out the usage of Button here

Agreed and updated in c452956

[github-actions]

Migration Safety Check

Found 8 potential issues:

20260128_213937_rename_appearance_to_variant.ts

Warning (line 6): ALTER keyword detected - review for data loss

sql`ALTER TABLE \`home_pages_blocks_link_preview_cards\` RENAME COLUMN "button_appearance" TO "button_variant";`,

Warning (line 6): RENAME keyword detected - review for data loss

sql`ALTER TABLE \`home_pages_blocks_link_preview_cards\` RENAME COLUMN "button_appearance" TO "button_variant";`,

Warning (line 9): ALTER keyword detected - review for data loss

sql`ALTER TABLE \`_home_pages_v_blocks_link_preview_cards\` RENAME COLUMN "button_appearance" TO "button_variant";`,

Warning (line 9): RENAME keyword detected - review for data loss

sql`ALTER TABLE \`_home_pages_v_blocks_link_preview_cards\` RENAME COLUMN "button_appearance" TO "button_variant";`,

Warning (line 12): ALTER keyword detected - review for data loss

sql`ALTER TABLE \`pages_blocks_link_preview_cards\` RENAME COLUMN "button_appearance" TO "button_variant";`,

Warning (line 12): RENAME keyword detected - review for data loss

sql`ALTER TABLE \`pages_blocks_link_preview_cards\` RENAME COLUMN "button_appearance" TO "button_variant";`,

Warning (line 15): ALTER keyword detected - review for data loss

sql`ALTER TABLE \`_pages_v_blocks_link_preview_cards\` RENAME COLUMN "button_appearance" TO "button_variant";`,

Warning (line 15): RENAME keyword detected - review for data loss

sql`ALTER TABLE \`_pages_v_blocks_link_preview_cards\` RENAME COLUMN "button_appearance" TO "button_variant";`,

---

Review these patterns and add backup/restore logic if needed. See docs/migration-safety.md for guidance.