From 68f56a7ffd314b760443a057db9ed1a982dbe191 Mon Sep 17 00:00:00 2001 From: HiDeoo Date: Fri, 16 Aug 2024 19:03:05 +0200 Subject: Add `` component (#1784) Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com> Co-authored-by: Chris Swithinbank --- .changeset/chilled-pots-eat.md | 5 ++ .changeset/thirty-students-sit.md | 16 +++++ docs/src/content/docs/guides/components.mdx | 32 +++++++++ docs/src/content/docs/index.mdx | 5 +- docs/src/content/docs/reference/frontmatter.md | 6 +- packages/starlight/components.ts | 1 + packages/starlight/components/CallToAction.astro | 51 --------------- packages/starlight/components/Hero.astro | 9 ++- packages/starlight/package.json | 4 -- packages/starlight/schemas/hero.ts | 4 +- .../starlight/user-components/LinkButton.astro | 76 ++++++++++++++++++++++ 11 files changed, 144 insertions(+), 65 deletions(-) create mode 100644 .changeset/chilled-pots-eat.md create mode 100644 .changeset/thirty-students-sit.md delete mode 100644 packages/starlight/components/CallToAction.astro create mode 100644 packages/starlight/user-components/LinkButton.astro diff --git a/.changeset/chilled-pots-eat.md b/.changeset/chilled-pots-eat.md new file mode 100644 index 00000000..e5c56b35 --- /dev/null +++ b/.changeset/chilled-pots-eat.md @@ -0,0 +1,5 @@ +--- +'@astrojs/starlight': minor +--- + +Adds `` component for visually distinct and emphasized call to action links diff --git a/.changeset/thirty-students-sit.md b/.changeset/thirty-students-sit.md new file mode 100644 index 00000000..1cfa90b6 --- /dev/null +++ b/.changeset/thirty-students-sit.md @@ -0,0 +1,16 @@ +--- +'@astrojs/starlight': minor +--- + +Changes the hero component action button default [variant](https://starlight.astro.build/reference/frontmatter/#heroconfig) from `minimal` to `primary`. + +If you want to preserve the previous behavior, hero component action buttons previously declared without a `variant` will need to be updated to include the `variant` property with the value `minimal`. + +```diff +hero: + actions: + - text: View on GitHub + link: https://github.com/astronaut/my-project + icon: external ++ variant: minimal +``` diff --git a/docs/src/content/docs/guides/components.mdx b/docs/src/content/docs/guides/components.mdx index 95a5e30f..4624a176 100644 --- a/docs/src/content/docs/guides/components.mdx +++ b/docs/src/content/docs/guides/components.mdx @@ -222,6 +222,38 @@ import { LinkCard } from '@astrojs/starlight/components'; +### Link Buttons + +Use the `` component for visually distinct call-to-action links. +A link button is useful for directing users to the most relevant or actionable content and often used on landing pages + +A `` requires an [`href`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href) attribute and optionally accepts other link attributes such as `target`. + +The `icon` attribute can optionally be set to the name of [one of Starlight's built-in icons](#all-icons) to include an icon next to the text. +The `iconPlacement` attribute can be used to place the icon before the text by setting it to `start` (defaults to `end`). + +Customize the appearance of the link button using the `variant` attribute, which can be set to `primary` (the default), `secondary`, or `minimal`. + +```mdx +# src/content/docs/example.mdx + +import { LinkButton } from '@astrojs/starlight/components'; + +Get started + + Related: Astro + +``` + +The above code generates the following on the page: + +import { LinkButton } from '@astrojs/starlight/components'; + +Get started + + Related: Astro + + ### Asides Asides (also known as “admonitions” or “callouts”) are useful for displaying secondary information alongside a page’s main content. diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 79c5ba60..d1dee8fe 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -15,10 +15,10 @@ hero: actions: - text: Get started icon: right-arrow - variant: primary link: /getting-started/ - text: View on GitHub icon: external + variant: minimal link: https://github.com/withastro/starlight --- @@ -69,8 +69,9 @@ import Testimonial from '~/components/testimonial.astro'; Starlight is our go-to example of a great DX: the speed, convenience, and attention to details is inspiring. It takes care of the tech and the looks, so you can focus on your content 👏 - + StackBlitz team absolutely loves it! + ; }>; } diff --git a/packages/starlight/components.ts b/packages/starlight/components.ts index 2935e9ff..67bf6b47 100644 --- a/packages/starlight/components.ts +++ b/packages/starlight/components.ts @@ -8,4 +8,5 @@ export { default as TabItem } from './user-components/TabItem.astro'; export { default as LinkCard } from './user-components/LinkCard.astro'; export { default as Steps } from './user-components/Steps.astro'; export { default as FileTree } from './user-components/FileTree.astro'; +export { default as LinkButton } from './user-components/LinkButton.astro'; export { Code } from 'astro-expressive-code/components'; diff --git a/packages/starlight/components/CallToAction.astro b/packages/starlight/components/CallToAction.astro deleted file mode 100644 index 551c64ea..00000000 --- a/packages/starlight/components/CallToAction.astro +++ /dev/null @@ -1,51 +0,0 @@ ---- -import type { HTMLAttributes } from 'astro/types'; -import Icon from '../user-components/Icon.astro'; -import type { Icons } from './Icons'; - -interface Props { - variant: 'primary' | 'secondary' | 'minimal'; - link: string; - icon?: undefined | { type: 'icon'; name: keyof typeof Icons } | { type: 'raw'; html: string }; - attrs?: Omit, 'href'> | undefined; -} - -const { link, variant, icon } = Astro.props; -const { class: customClass, ...attrs } = Astro.props.attrs || {}; ---- - - - - {icon?.type === 'icon' && } - {icon?.type === 'raw' && } - - - diff --git a/packages/starlight/components/Hero.astro b/packages/starlight/components/Hero.astro index f763ce22..51be009a 100644 --- a/packages/starlight/components/Hero.astro +++ b/packages/starlight/components/Hero.astro @@ -2,7 +2,7 @@ import { Image } from 'astro:assets'; import { PAGE_TITLE_ID } from '../constants'; import type { Props } from '../props'; -import CallToAction from './CallToAction.astro'; +import LinkButton from '../user-components/LinkButton.astro'; const { data } = Astro.props.entry; const { title = data.title, tagline, image, actions = [] } = data.hero || {}; @@ -50,8 +50,11 @@ if (image) { { actions.length > 0 && (
- {actions.map(({ text, ...attrs }) => ( - + {actions.map(({ attrs, icon, link: href, text, variant }) => ( + + {text} + {icon?.html && } + ))}
) diff --git a/packages/starlight/package.json b/packages/starlight/package.json index 1efba7a4..d331676a 100644 --- a/packages/starlight/package.json +++ b/packages/starlight/package.json @@ -47,10 +47,6 @@ "types": "./components/Sidebar.astro.tsx", "import": "./components/Sidebar.astro" }, - "./components/CallToAction.astro": { - "types": "./components/CallToAction.astro.tsx", - "import": "./components/CallToAction.astro" - }, "./components/MarkdownContent.astro": { "types": "./components/MarkdownContent.astro.tsx", "import": "./components/MarkdownContent.astro" diff --git a/packages/starlight/schemas/hero.ts b/packages/starlight/schemas/hero.ts index 0c335124..6ecc50df 100644 --- a/packages/starlight/schemas/hero.ts +++ b/packages/starlight/schemas/hero.ts @@ -49,8 +49,8 @@ export const HeroSchema = ({ image }: SchemaContext) => text: z.string(), /** Value for the link’s `href` attribute, e.g. `/page` or `https://mysite.com`. */ link: z.string(), - /** Button style to use. One of `primary`, `secondary`, or `minimal` (the default). */ - variant: z.enum(['primary', 'secondary', 'minimal']).default('minimal'), + /** Button style to use. One of `primary` (the default), `secondary`, or `minimal`. */ + variant: z.enum(['primary', 'secondary', 'minimal']).default('primary'), /** * An optional icon to display alongside the link text. * Can be an inline `` or the name of one of Starlight’s built-in icons. diff --git a/packages/starlight/user-components/LinkButton.astro b/packages/starlight/user-components/LinkButton.astro new file mode 100644 index 00000000..3bf68f07 --- /dev/null +++ b/packages/starlight/user-components/LinkButton.astro @@ -0,0 +1,76 @@ +--- +import type { HTMLAttributes } from 'astro/types'; +import { Icons } from '../components/Icons'; +import Icon from './Icon.astro'; + +interface Props extends Omit, 'href'> { + href: string | URL; + icon?: keyof typeof Icons | undefined; + iconPlacement?: 'start' | 'end' | undefined; + variant?: 'primary' | 'secondary' | 'minimal'; +} + +const { + class: className, + icon, + iconPlacement = 'end', + variant = 'primary', + ...attrs +} = Astro.props; +--- + + + {icon && iconPlacement === 'start' && } + + {icon && iconPlacement === 'end' && } + + + -- cgit