diff --git a/.changeset/wicked-melons-study.md b/.changeset/wicked-melons-study.md new file mode 100644 index 0000000000..9de08e60dd --- /dev/null +++ b/.changeset/wicked-melons-study.md @@ -0,0 +1,6 @@ +--- +'@astrojs/starlight': minor +--- + +Adds a new `` component + diff --git a/docs/src/content/docs/guides/components.mdx b/docs/src/content/docs/guides/components.mdx index 30178aec7d..95a5e30f2d 100644 --- a/docs/src/content/docs/guides/components.mdx +++ b/docs/src/content/docs/guides/components.mdx @@ -412,6 +412,36 @@ import { Steps } from '@astrojs/starlight/components'; +### Badges + +import { Badge } from '@astrojs/starlight/components'; + +Use the `` component to display small pieces of information, such as status or labels. + +Pass the content you want to display to the `text` attribute of the `` component. + +By default, the badge will use the theme accent color of your site. To use a built-in badge color, set the `variant` attribute to one of the following values: `note` (blue), `tip` (purple), `danger` (red), `caution` (orange), or `success` (green). + +The `size` attribute (default: `small`) controls the size of the badge text. `medium` and `large` are also available options for displaying a larger badge. + +For further customization, use other `` attributes such as `class` or `style` with custom CSS. + +```mdx title="src/content/docs/example.mdx" +import { Badge } from '@astrojs/starlight/components'; + + + + + +``` + +The code above generates the following on the page: + + + + + + ### Icon import { Icon } from '@astrojs/starlight/components'; diff --git a/docs/src/content/docs/guides/sidebar.mdx b/docs/src/content/docs/guides/sidebar.mdx index bf9d360564..0632b53713 100644 --- a/docs/src/content/docs/guides/sidebar.mdx +++ b/docs/src/content/docs/guides/sidebar.mdx @@ -294,12 +294,14 @@ The configuration above generates the following sidebar: ]} /> -### Badge variants +### Badge variants and custom styling -Customize the badge styling using an object with `text` and `variant` properties. +Customize the badge styling using an object with `text`, `variant`, and `class` properties. The `text` represents the content to display (e.g. "New"). -Override the `default` styling, which uses the accent color of your site, by setting the `variant` property to one of the following values: `note`, `tip`, `danger`, `caution` or `success`. +By default, the badge will use the accent color of your site. To use a built-in badge style, set the `variant` property to one of the following values: `note`, `tip`, `danger`, `caution` or `success`. + +Optionally, you can create a custom badge style by setting the `class` property to a CSS class name. ```js {10} starlight({ diff --git a/docs/src/content/docs/reference/configuration.mdx b/docs/src/content/docs/reference/configuration.mdx index a940a844ea..59816e1a87 100644 --- a/docs/src/content/docs/reference/configuration.mdx +++ b/docs/src/content/docs/reference/configuration.mdx @@ -214,7 +214,8 @@ type SidebarItem = { ```ts interface BadgeConfig { text: string; - variant: 'note' | 'tip' | 'caution' | 'danger' | 'success' | 'default'; + variant?: 'note' | 'tip' | 'caution' | 'danger' | 'success' | 'default'; + class?: string; } ``` diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md index 32ae46cabd..41fc4a5b78 100644 --- a/docs/src/content/docs/reference/frontmatter.md +++ b/docs/src/content/docs/reference/frontmatter.md @@ -355,7 +355,7 @@ sidebar: Add a badge to the page in the sidebar when displayed in an autogenerated group of links. When using a string, the badge will be displayed with a default accent color. -Optionally, pass a [`BadgeConfig` object](/reference/configuration/#badgeconfig) with `text` and `variant` fields to customize the badge. +Optionally, pass a [`BadgeConfig` object](/reference/configuration/#badgeconfig) with `text`, `variant`, and `class` fields to customize the badge. ```md --- diff --git a/packages/starlight/components.ts b/packages/starlight/components.ts index e564b62b73..2935e9fff8 100644 --- a/packages/starlight/components.ts +++ b/packages/starlight/components.ts @@ -1,4 +1,5 @@ export { default as Aside } from './user-components/Aside.astro'; +export { default as Badge } from './user-components/Badge.astro'; export { default as Card } from './user-components/Card.astro'; export { default as CardGrid } from './user-components/CardGrid.astro'; export { default as Icon } from './user-components/Icon.astro'; diff --git a/packages/starlight/components/Badge.astro b/packages/starlight/components/Badge.astro deleted file mode 100644 index 7e8c0da2d4..0000000000 --- a/packages/starlight/components/Badge.astro +++ /dev/null @@ -1,87 +0,0 @@ ---- -import type { Badge } from '../schemas/badge'; - -interface Props { - variant?: Badge['variant'] | 'outline'; - text?: string; -} -const { variant = 'default', text } = Astro.props; ---- - - - - diff --git a/packages/starlight/components/SidebarSublist.astro b/packages/starlight/components/SidebarSublist.astro index 399d191fa9..232525016e 100644 --- a/packages/starlight/components/SidebarSublist.astro +++ b/packages/starlight/components/SidebarSublist.astro @@ -1,7 +1,7 @@ --- import { flattenSidebar, type SidebarEntry } from '../utils/navigation'; import Icon from '../user-components/Icon.astro'; -import Badge from './Badge.astro'; +import Badge from '../user-components/Badge.astro'; interface Props { sublist: SidebarEntry[]; @@ -24,13 +24,11 @@ const { sublist, nested } = Astro.props; > {entry.label} {entry.badge && ( - <> - {' '} - - + )} ) : ( @@ -41,10 +39,11 @@ const { sublist, nested } = Astro.props;
{entry.label} {entry.badge && ( - <> - {' '} - - + )}
diff --git a/packages/starlight/schemas/badge.ts b/packages/starlight/schemas/badge.ts index dc6fdb67a1..a2cac1b177 100644 --- a/packages/starlight/schemas/badge.ts +++ b/packages/starlight/schemas/badge.ts @@ -4,8 +4,17 @@ const badgeSchema = () => z.object({ variant: z.enum(['note', 'danger', 'success', 'caution', 'tip', 'default']).default('default'), text: z.string(), + class: z.string().optional(), }); +export const BadgeComponentSchema = badgeSchema() + .extend({ + size: z.enum(['small', 'medium', 'large']).default('small'), + }) + .passthrough(); + +export type BadgeComponentProps = z.input; + export const BadgeConfigSchema = () => z .union([z.string(), badgeSchema()]) diff --git a/packages/starlight/user-components/Badge.astro b/packages/starlight/user-components/Badge.astro new file mode 100644 index 0000000000..821cd0a32e --- /dev/null +++ b/packages/starlight/user-components/Badge.astro @@ -0,0 +1,141 @@ +--- +import { BadgeComponentSchema, type BadgeComponentProps } from '../schemas/badge'; +import { parseWithFriendlyErrors } from '../utils/error-map'; +import type { HTMLAttributes } from 'astro/types'; + +type Props = BadgeComponentProps & HTMLAttributes<'span'>; + +const { + text, + variant, + size, + class: customClass, + ...attrs +} = parseWithFriendlyErrors( + BadgeComponentSchema, + Astro.props, + 'Invalid prop passed to the `` component.' +); +--- + +{text} + +