@grove-dev/starlight 0.6.1 → 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Turtuvshin Byambaa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,83 +1,49 @@
-# @grove-dev/starlight
+# `@grove-dev/starlight`
 
-Grove Starlight is a theme plugin for Astro Starlight that powers the
-Grove documentation site (`apps/docs/`). It ships component overrides,
-a layered CSS theme, and an Expressive Code integration so that
-Starlight renders pages in the same visual language as Grove-powered
-directories.
+The Starlight theme and documentation integration used by Grove.
+It powers the Grove documentation site (`apps/docs/`) and is
+available as a Starlight plugin for any documentation project that
+wants the same visual language as Grove-powered sites.
 
-## Features
+The plugin registers component overrides for the header, sidebar,
+page frame, hero, footer, search, table of contents, pagination,
+and Markdown content. It appends a layered CSS theme with light and
+dark mode values and configures Expressive Code so code blocks
+match the rest of the site.
 
-- Starlight plugin API integration.
-- Custom overrides for header, sidebar, page frame, hero, footer, search, table of contents, pagination, and Markdown content.
-- Token-based, layered CSS theme with light and dark mode values.
-- Styled built-in Starlight components including hero splashes, cards, link cards, asides, badges, tabs, steps, file trees, and link buttons.
-
-## Installation
+## Install
 
 ```bash
-npm install @grove-dev/starlight
+pnpm add @grove-dev/starlight
 ```
 
-With Bun:
-
-```bash
-bun add @grove-dev/starlight
-```
+Requires Node.js `>=22.12.0`, Astro `>=5.0.0`, and
+`@astrojs/starlight >=0.38.3`.
 
-## Usage
+## Use the plugin
 
 Add the plugin inside the Starlight integration:
 
 ```js
 // astro.config.mjs
-import { defineConfig } from 'astro/config';
-import starlight from '@astrojs/starlight';
-import grove from '@grove-dev/starlight';
+import { defineConfig } from "astro/config";
+import starlight from "@astrojs/starlight";
+import grove from "@grove-dev/starlight";
 
 export default defineConfig({
   integrations: [
     starlight({
-      title: 'My Docs',
+      title: "My Docs",
       plugins: [grove()],
     }),
   ],
 });
 ```
 
-The plugin registers Grove's component overrides, appends the theme
-CSS files, and configures Expressive Code.
-
-## Attribution
-
-This theme recreates the design of the documentation site for
-[shadcn/ui](https://ui.shadcn.com/).
+The plugin registers Grove's component overrides, appends the
+theme CSS files, and configures Expressive Code.
 
-It uses [adrian-ub/starlight-theme-black](https://github.com/adrian-ub/starlight-theme-black)
-as a base, which brought an earlier shadcn/ui-inspired design to Astro
-Starlight.
-
-## Docs Schema
-
-To use Grove's splash-page frontmatter fields with type checking,
-extend the Starlight docs schema:
-
-```ts
-// src/content.config.ts
-import { defineCollection } from 'astro:content';
-import { docsLoader } from '@astrojs/starlight/loaders';
-import { docsSchema } from '@astrojs/starlight/schema';
-import { ExtendDocsSchema } from '@grove-dev/starlight/schema';
-
-export const collections = {
-  docs: defineCollection({
-    loader: docsLoader(),
-    schema: docsSchema({ extend: ExtendDocsSchema }),
-  }),
-};
-```
-
-## Plugin Options
+## Plugin options
 
 ```ts
 type GroveStarlightUserConfig = {
@@ -93,20 +59,38 @@ type Link = {
 };
 ```
 
-Example:
-
 ```js
 grove({
   navLinks: [
-    { label: 'Docs', link: '/introduction/' },
-    { label: 'GitHub', link: 'https://github.com/tortuvshin/grove' },
+    { label: "Docs", link: "/introduction/" },
+    { label: "GitHub", link: "https://github.com/tortuvshin/grove" },
   ],
   footerText:
-    'Built with [Grove Starlight](https://github.com/tortuvshin/grove/tree/main/packages/starlight).',
+    "Built with [Grove Starlight](https://github.com/tortuvshin/grove/tree/main/packages/starlight).",
 });
 ```
 
-## Splash Pages
+## Extend the docs schema
+
+To use Grove's splash-page frontmatter fields with type checking,
+extend the Starlight docs schema:
+
+```ts
+// src/content.config.ts
+import { defineCollection } from "astro:content";
+import { docsLoader } from "@astrojs/starlight/loaders";
+import { docsSchema } from "@astrojs/starlight/schema";
+import { ExtendDocsSchema } from "@grove-dev/starlight/schema";
+
+export const collections = {
+  docs: defineCollection({
+    loader: docsLoader(),
+    schema: docsSchema({ extend: ExtendDocsSchema }),
+  }),
+};
+```
+
+## Splash pages
 
 Use Starlight's `template: splash` and set `hero.layout`:
 
@@ -141,7 +125,7 @@ Import user-facing components from `@grove-dev/starlight/components`:
 
 ```astro
 ---
-import { ContainerSection, Dropdown, LinkButton } from '@grove-dev/starlight/components';
+import { ContainerSection, Dropdown, LinkButton } from "@grove-dev/starlight/components";
 ---
 
 <ContainerSection width="lg">
@@ -167,30 +151,29 @@ import { ContainerSection, Dropdown, LinkButton } from '@grove-dev/starlight/com
 
 ### `LinkButton`
 
-Props:
-
-- `href`: anchor destination.
-- `variant`: `primary`, `secondary`, or `minimal`.
-- `size`: `2xs`, `xs`, `sm`, `md`, or `lg`.
+- `href` — anchor destination.
+- `variant` — `primary`, `secondary`, or `minimal`.
+- `size` — `2xs`, `xs`, `sm`, `md`, or `lg`.
 - Other anchor attributes are forwarded.
 
 ### `ContainerSection`
 
-Props:
-
-- `width`: `sm`, `md`, `lg`, or `xl`.
+- `width` — `sm`, `md`, `lg`, or `xl`.
 
 ### `Dropdown`
 
-Compound menu component exported as `Dropdown.Root`, `Dropdown.Trigger`, `Dropdown.Content`, `Dropdown.Item`, `Dropdown.Label`, `Dropdown.Separator`, and `Dropdown.Shortcut`.
+Compound menu component exported as `Dropdown.Root`,
+`Dropdown.Trigger`, `Dropdown.Content`, `Dropdown.Item`,
+`Dropdown.Label`, `Dropdown.Separator`, and `Dropdown.Shortcut`.
 
 Useful props:
 
-- `Dropdown.Root`: `openOnHover`, `closeDelay`.
-- `Dropdown.Trigger`: `asChild`, `variant`, `size`.
-- `Dropdown.Content`: `side`, `align`, `sideOffset`, `animationDuration`.
-- `Dropdown.Item`: `as`, `inset`, `disabled`.
-- `Dropdown.Label`: `inset`.
+- `Dropdown.Root` — `openOnHover`, `closeDelay`.
+- `Dropdown.Trigger` — `asChild`, `variant`, `size`.
+- `Dropdown.Content` — `side`, `align`, `sideOffset`,
+  `animationDuration`.
+- `Dropdown.Item` — `as`, `inset`, `disabled`.
+- `Dropdown.Label` — `inset`.
 
 ## Styling
 
@@ -204,6 +187,22 @@ Override theme tokens from your app CSS:
 }
 ```
 
+## Attribution
+
+This theme recreates the design of the documentation site for
+[shadcn/ui](https://ui.shadcn.com/).
+
+It uses
+[adrian-ub/starlight-theme-black](https://github.com/adrian-ub/starlight-theme-black)
+as a base, which brought an earlier shadcn/ui-inspired design to
+Astro Starlight.
+
+## Develop Starlight
+
+```bash
+pnpm --filter @grove-dev/starlight test
+```
+
 ## License
 
-MIT
+[MIT](../../LICENSE) © Grove contributors.

package/components/custom/ContainerSection.astro

@@ -1,6 +1,6 @@
 ---
 type Props = {
-    width?: 'sm' | 'md' | 'lg' | 'xl';
+  width?: 'sm' | 'md' | 'lg' | 'xl';
 };
 
 const { width = 'lg' } = Astro.props;

package/components/custom/LinkButton.astro

@@ -1,141 +1,186 @@
 ---
 import type { HTMLAttributes } from 'astro/types';
 
+export type ButtonVariant = 'default' | 'link' | 'secondary' | 'outline' | 'ghost' | 'destructive';
+
+/**
+ * Starlight's own hero action variants. Kept as aliases of their shadcn equivalents so existing
+ * frontmatter and `<LinkButton>` usage keeps working.
+ */
+export type LegacyButtonVariant = 'primary' | 'minimal';
+
+const LEGACY_VARIANTS = {
+  primary: 'default',
+  minimal: 'ghost',
+} as const satisfies Record<LegacyButtonVariant, ButtonVariant>;
+
 type Props = (Omit<HTMLAttributes<'a'>, 'href'> | HTMLAttributes<'button'>) & {
-    href?: string | URL | null | undefined;
-    variant?: 'primary' | 'secondary' | 'minimal';
-    size?: '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'icon-sm' | 'icon-md' | 'icon-lg';
+  /** Renders an `<a>` when set, a `<button>` otherwise. */
+  href?: string | URL | null | undefined;
+  variant?: ButtonVariant | LegacyButtonVariant;
+  size?: '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'icon-sm' | 'icon-md' | 'icon-lg';
 };
 
-const { class: className, variant = 'primary', size = 'md', ...attrs } = Astro.props;
+const { class: className, variant = 'default', size = 'md', ...attrs } = Astro.props;
+
+// Normalise so the stylesheet only ever has to know about the canonical variant names.
+const resolvedVariant: ButtonVariant =
+  LEGACY_VARIANTS[variant as LegacyButtonVariant] ?? (variant as ButtonVariant);
 
 const Tag = attrs.href ? 'a' : 'button';
 ---
 
 <Tag
     data-slot="button"
-    class:list={['link-button', variant, className]}
+    data-variant={resolvedVariant}
     data-size={size}
+    class:list={['link-button', className]}
     {...attrs as any}
 >
     <slot />
 </Tag>
 
 <style>
-    [data-slot='button'],
+    /*
+     * Styling is anchored on `.link-button`, never on `data-slot`. Consumers are allowed to replace
+     * `data-slot` with their own value — `DropdownTrigger` does, because `Dropdown.astro` queries
+     * `[data-slot='dropdown-trigger']` — so keying styles off it would silently unstyle them.
+     */
     .link-button {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        white-space: nowrap;
+        gap: 0.5rem;
+        font-weight: var(--button-font-weight, 500);
+        border: none;
+        text-decoration: inherit;
         transition-property:
             color, background-color, border-color, text-decoration-color, fill, stroke;
         transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
         transition-duration: 0.15s;
-        color: var(--primary-foreground);
-        white-space: nowrap;
-        gap: 0.5rem;
-        justify-content: center;
-        align-items: center;
-        display: inline-flex;
-        text-decoration: inherit;
-        border: none;
-
+        border-radius: var(--button-radius, var(--radius));
         height: var(--button-height, calc(var(--spacing) * 8));
         width: var(--button-width, auto);
-        font-weight: var(--button-font-weight, 500);
-        font-size: var(--button-font-size, 0.875rem);
-        line-height: var(--button-line-height, 1rem);
         padding-left: var(--button-padding-l, var(--button-padding-x, calc(var(--spacing) * 2.5)));
         padding-right: var(--button-padding-r, var(--button-padding-x, calc(var(--spacing) * 2.5)));
-        border-radius: var(--button-radius, var(--radius));
+        font-size: var(--button-font-size, 0.875rem);
+        line-height: var(--button-line-height, 1rem);
+    }
 
-        &[data-size='2xs'] {
-            --button-height: calc(var(--spacing) * 5.5);
-            --button-padding-l: calc(var(--spacing) * 2);
-            --button-padding-r: var(--spacing);
-            --button-font-size: 0.75rem;
-            --border-radius: 100%;
-        }
+    [data-size='2xs'] {
+        --button-height: calc(var(--spacing) * 5.5);
+        --button-padding-l: calc(var(--spacing) * 2);
+        --button-padding-r: var(--spacing);
+        --button-font-size: 0.75rem;
+    }
 
-        &[data-size='xs'] {
-            --button-radius: calc(var(--radius) - 2px);
-            --button-height: calc(var(--spacing) * 6);
-            --button-padding-x: calc(var(--spacing) * 2);
-            --button-font-size: 0.75rem;
-        }
+    [data-size='xs'] {
+        --button-radius: calc(var(--radius) - 2px);
+        --button-height: calc(var(--spacing) * 6);
+        --button-padding-x: calc(var(--spacing) * 2);
+        --button-font-size: 0.75rem;
+    }
 
-        &[data-size='sm'] {
-            --button-height: calc(var(--spacing) * 7);
-            --button-padding-x: calc(var(--spacing) * 2.5);
-            --button-font-size: 0.8rem;
-        }
+    [data-size='sm'] {
+        --button-height: calc(var(--spacing) * 7);
+        --button-padding-x: calc(var(--spacing) * 2.5);
+        --button-font-size: 0.8rem;
+    }
 
-        &[data-size='lg'] {
-            --button-height: calc(var(--spacing) * 8.5);
-            --button-padding-x: calc(var(--spacing) * 2.5);
-            --button-font-size: 0.875rem;
-        }
+    [data-size='lg'] {
+        --button-height: calc(var(--spacing) * 8.5);
+        --button-padding-x: calc(var(--spacing) * 2.5);
+        --button-font-size: 0.875rem;
+    }
+
+    [data-size='icon-sm'],
+    [data-size='icon-md'],
+    [data-size='icon-lg'] {
+        --button-padding-x: 0;
+        --button-font-size: 0;
+    }
+
+    [data-size='icon-sm'] {
+        --button-radius: calc(var(--radius) - 3px);
+        --button-height: calc(var(--spacing) * 6);
+        --button-width: calc(var(--spacing) * 6);
 
-        &[data-size='icon-sm'] {
-            --button-height: calc(var(--spacing) * 6);
-            --button-width: calc(var(--spacing) * 6);
-            --button-padding-x: 0;
-            --button-font-size: 0;
-            --button-radius: calc(var(--radius) - 3px);
-
-            svg {
-                width: 1rem;
-                height: 1rem;
-            }
+        svg {
+            width: 1rem;
+            height: 1rem;
         }
+    }
+
+    [data-size='icon-md'] {
+        --button-radius: calc(var(--radius) - 2px);
+        --button-height: calc(var(--spacing) * 7);
+        --button-width: calc(var(--spacing) * 7);
 
-        &[data-size='icon-md'] {
-            --button-height: calc(var(--spacing) * 7);
-            --button-width: calc(var(--spacing) * 7);
-            --button-padding-x: 0;
-            --button-font-size: 0;
-            --button-radius: calc(var(--radius) - 2px);
-
-            svg {
-                width: 1.25rem;
-                height: 1.25rem;
-            }
+        svg {
+            width: 1.25rem;
+            height: 1.25rem;
         }
+    }
+
+    [data-size='icon-lg'] {
+        --button-radius: calc(var(--radius) - 1px);
+        --button-height: calc(var(--spacing) * 8);
+        --button-width: calc(var(--spacing) * 8);
 
-        &[data-size='icon-lg'] {
-            --button-height: calc(var(--spacing) * 8);
-            --button-width: calc(var(--spacing) * 8);
-            --button-padding-x: 0;
-            --button-font-size: 0;
-            --button-radius: calc(var(--radius) - 1px);
-
-            svg {
-                width: 1.5rem;
-                height: 1.5rem;
-            }
+        svg {
+            width: 1.5rem;
+            height: 1.5rem;
         }
     }
 
-    .primary {
-        background-color: var(--primary);
+    [data-variant='secondary'] {
+        background: var(--secondary);
+        color: var(--secondary-foreground);
+    }
+    [data-variant='secondary']:hover {
+        background: color-mix(in oklab, var(--secondary) 80%, transparent);
     }
 
-    .primary:hover {
-        background-color: color-mix(in oklab, var(--primary) 90%, transparent);
+    [data-variant='default'] {
+        background: var(--primary);
+        color: var(--primary-foreground);
+    }
+    [data-variant='default']:hover {
+        background: color-mix(in oklab, var(--primary) 90%, transparent);
     }
 
-    .secondary {
-        background-color: var(--secondary);
-        color: var(--secondary-foreground);
+    [data-variant='outline'] {
+        border: 1px solid var(--border);
+        background: var(--background);
+        color: var(--foreground);
+    }
+    [data-variant='outline']:hover {
+        background: var(--muted);
     }
 
-    .secondary:hover {
-        background-color: color-mix(in oklab, var(--secondary) 80%, transparent);
+    [data-variant='ghost'] {
+        background: transparent;
+        color: var(--foreground);
+    }
+    [data-variant='ghost']:hover {
+        background: var(--muted);
     }
 
-    .minimal {
-        color: var(--accent-foreground);
+    [data-variant='destructive'] {
+        background: color-mix(in oklab, var(--destructive) 10%, transparent);
+        color: var(--destructive);
+    }
+    [data-variant='destructive']:hover {
+        background: color-mix(in oklab, var(--destructive) 20%, transparent);
     }
 
-    .minimal:hover {
-        color: var(--accent-foreground);
-        background-color: var(--accent);
+    [data-variant='link'] {
+        background: none;
+        color: var(--primary);
+        text-underline-offset: 4px;
+    }
+    [data-variant='link']:hover {
+        text-decoration: underline;
     }
 </style>

package/components/custom/dropdown/Dropdown.astro

@@ -2,11 +2,11 @@
 import type { HTMLAttributes } from 'astro/types';
 
 type Props = HTMLAttributes<'div'> & {
-    /** When true, the dropdown will open on hover in addition to click */
-    openOnHover?: boolean;
-    /** Time in milliseconds to wait before closing when hover open is enabled (defaults to 200) */
-    closeDelay?: number;
-    children: any;
+  /** When true, the dropdown will open on hover in addition to click */
+  openOnHover?: boolean;
+  /** Time in milliseconds to wait before closing when hover open is enabled (defaults to 200) */
+  closeDelay?: number;
+  children: any;
 };
 
 const { class: className, openOnHover = false, closeDelay = 200, ...rest } = Astro.props;