@publier/shell 2.1.1

package/src/components/types.ts

@@ -0,0 +1,510 @@
+/**
+ * Public prop types for the Astro-rendered shell components.
+ *
+ * These live in a separate `.ts` file (rather than inline in each `.astro`'s
+ * frontmatter) so the barrel `index.ts` can re-export them without relying
+ * on TypeScript's `.astro` module inference — which is only provided in
+ * Astro build contexts, not during our plain `tsc --noEmit` check.
+ */
+
+// ---------------------------------------------------------------------------
+// AnnouncementBanner
+// ---------------------------------------------------------------------------
+
+export type AnnouncementBannerVariant = 'info' | 'warning' | 'success';
+
+export interface AnnouncementBannerProps {
+	/** Plain text message displayed inside the banner. */
+	message: string;
+	/** Optional URL; wraps the message in an anchor when provided. */
+	href?: string;
+	/** Semantic variant controlling the color scheme. Default: `'info'`. */
+	variant?: AnnouncementBannerVariant;
+	/** Whether the banner can be dismissed. Default: `true`. */
+	dismissible?: boolean;
+	/** localStorage key used to persist the dismissed state. Default: `'publier-banner-dismissed'`. */
+	storageKey?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Aside / callouts
+// ---------------------------------------------------------------------------
+
+export type AsideType = 'note' | 'tip' | 'caution' | 'danger';
+
+export interface AsideProps {
+	/** Semantic variant. Default: `'note'`. */
+	type?: AsideType;
+	/** Title text. Defaults to a localized variant label (`Note`, `Tip`, ...). */
+	title?: string;
+}
+
+export interface CalloutProps {
+	/** Override the callout's header text. */
+	title?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Badge
+// ---------------------------------------------------------------------------
+
+export type BadgeVariant = 'default' | 'note' | 'tip' | 'caution' | 'danger' | 'success';
+export type BadgeSize = 'small' | 'medium' | 'large';
+
+export interface BadgeProps {
+	/** Text displayed inside the badge. Required. */
+	text: string;
+	/** Semantic variant. Default: `'default'`. */
+	variant?: BadgeVariant;
+	/** Size. Default: `'medium'`. */
+	size?: BadgeSize;
+	/** Additional class names to append. */
+	class?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Breadcrumbs
+// ---------------------------------------------------------------------------
+
+export interface BreadcrumbItem {
+	/** Visible text for the breadcrumb entry. */
+	label: string;
+	/**
+	 * Destination URL. Omit for the last item — the current page — which is
+	 * rendered as plain text with `aria-current="page"`.
+	 */
+	href?: string;
+}
+
+export interface BreadcrumbsProps {
+	/** Ordered breadcrumb trail, outermost ancestor first. */
+	items: BreadcrumbItem[];
+	/** Accessible label for the <nav> landmark. Default: `'Breadcrumb'`. */
+	label?: string;
+	/** Additional class names to append to the root element. */
+	class?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Card / CardGrid
+// ---------------------------------------------------------------------------
+
+export type CardVariant = 'default' | 'note' | 'tip' | 'danger' | 'success';
+
+export interface CardProps {
+	/** Title text rendered in the card's header row. Required. */
+	title: string;
+	/** Semantic variant; drives the accent border + icon tint. Default: `'default'`. */
+	variant?: CardVariant;
+	/** Additional class names to append. */
+	class?: string;
+}
+
+export interface CardGridProps {
+	/** Minimum column width before the grid wraps. Defaults to `'15rem'`. */
+	minColumnWidth?: string;
+	/** Additional class names to append. */
+	class?: string;
+}
+
+// ---------------------------------------------------------------------------
+// CodeGroup
+// ---------------------------------------------------------------------------
+
+export interface CodeGroupItem {
+	/** Tab label. */
+	label: string;
+	/** Raw code string to display. */
+	code: string;
+	/** Language identifier for the `language-*` class. */
+	lang?: string;
+	/** Optional filename shown as a secondary label below the tab strip. */
+	filename?: string;
+}
+
+export interface CodeGroupProps {
+	/** Ordered code tabs. */
+	items: CodeGroupItem[];
+	/** Cross-page sync key — CodeGroup instances with the same key stay aligned. */
+	syncKey?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Columns
+// ---------------------------------------------------------------------------
+
+export type ColumnCount = 2 | 3 | 4;
+export type ColumnGap = 'sm' | 'md' | 'lg';
+
+export interface ColumnsProps {
+	/** Number of equal-width columns. Default: `2`. */
+	cols?: ColumnCount;
+	/** Gap size between columns. Default: `'md'`. */
+	gap?: ColumnGap;
+	/** Additional class names to append. */
+	class?: string;
+}
+
+// ---------------------------------------------------------------------------
+// DocsLayout
+// ---------------------------------------------------------------------------
+
+export interface DocsLayoutProps {
+	/** Additional class names to append to the outermost wrapper. */
+	class?: string;
+	/** Optional breadcrumb trail rendered above the article slot. */
+	breadcrumbs?: BreadcrumbItem[];
+	/** Optional last-modified date rendered below breadcrumbs. */
+	lastModified?: Date | string | null;
+}
+
+// ---------------------------------------------------------------------------
+// FileTree
+// ---------------------------------------------------------------------------
+
+export type FileTreeEntry = FileTreeFile | FileTreeDirectory | FileTreePlaceholder;
+
+export interface FileTreeFile {
+	type: 'file';
+	/** Filename with extension (e.g. `README.md`, `index.test.ts`). */
+	name: string;
+	/** Render as the "highlighted" entry. */
+	highlight?: boolean;
+	/** Optional comment rendered after the filename. */
+	comment?: string;
+}
+
+export interface FileTreeDirectory {
+	type: 'directory';
+	/** Folder name (trailing slash is auto-added). */
+	name: string;
+	/** Children (files or sub-directories). */
+	children: FileTreeEntry[];
+	/** If `true`, the `<details>` opens on first render. Default: `true`. */
+	open?: boolean;
+	/** Render as the "highlighted" entry. */
+	highlight?: boolean;
+	/** Optional comment rendered after the folder name. */
+	comment?: string;
+}
+
+export interface FileTreePlaceholder {
+	type: 'placeholder';
+	/** Custom ellipsis text. Defaults to `'…'`. */
+	name?: string;
+	/** Optional comment rendered after the placeholder. */
+	comment?: string;
+}
+
+export interface FileTreeProps {
+	/** Top-level entries. */
+	tree: FileTreeEntry[];
+	/** Accessible label for the tree region. Default: `'File tree'`. */
+	label?: string;
+	/** Additional class names. */
+	class?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Icon
+// ---------------------------------------------------------------------------
+
+export interface IconProps {
+	/** Icon name from the Publier icon registry (case-sensitive). */
+	name: string;
+	/** Icon size in px. Default: `16`. */
+	size?: number;
+	/** Additional CSS class names on the wrapper span. */
+	class?: string;
+}
+
+// ---------------------------------------------------------------------------
+// LinkButton / LinkCard
+// ---------------------------------------------------------------------------
+
+export type LinkButtonVariant = 'primary' | 'secondary' | 'minimal';
+export type LinkButtonIconPlacement = 'start' | 'end';
+
+export interface LinkButtonProps {
+	/** Destination URL. Required. */
+	href: string;
+	/** Visual style. Default: `'primary'`. */
+	variant?: LinkButtonVariant;
+	/** Optional icon placement relative to the label slot. Default: `'end'`. */
+	iconPlacement?: LinkButtonIconPlacement;
+	/** Optional rel attribute on the anchor. */
+	rel?: string;
+	/** Optional target attribute on the anchor. */
+	target?: '_blank' | '_self' | '_parent' | '_top';
+	/** Additional class names to append. */
+	class?: string;
+}
+
+export interface LinkCardProps {
+	/** Title text. Required. */
+	title: string;
+	/** Destination URL. Required. */
+	href: string;
+	/** Secondary descriptive text below the title. */
+	description?: string;
+	/** Optional rel attribute on the anchor. */
+	rel?: string;
+	/** Optional target attribute on the anchor. */
+	target?: '_blank' | '_self' | '_parent' | '_top';
+	/** Additional class names to append. */
+	class?: string;
+}
+
+// ---------------------------------------------------------------------------
+// OpenInAI
+// ---------------------------------------------------------------------------
+
+export interface OpenInAIProps {
+	/** Full URL of the current page (pass `Astro.url.href` from the parent). */
+	pageUrl?: string;
+	/** Page title used in the "Copy as Markdown" action. */
+	pageTitle?: string;
+}
+
+// ---------------------------------------------------------------------------
+// PackageInstall
+// ---------------------------------------------------------------------------
+
+export interface PackageInstallProps {
+	/** Package name to install. Used for 'prod' and 'dev' types. */
+	pkg?: string;
+	/** Install type: 'prod' (default), 'dev' (`-D`), or 'exec' (for `bunx`). */
+	type?: 'prod' | 'dev' | 'exec';
+	/** Raw command for exec type. Overrides pkg when set. */
+	command?: string;
+	/**
+	 * Accepted for backward compatibility with pages written when
+	 * `<PackageInstall>` rendered four package-manager tabs. The component is
+	 * now single-PM (Publier uses pnpm as PM, bun as runtime) — there is no
+	 * cross-instance selector to drive, so the value is ignored.
+	 *
+	 * @deprecated The component renders a single command (`pnpm add` for
+	 * prod/dev, `bunx` for exec); sync keys no longer apply.
+	 */
+	syncKey?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Panels
+// ---------------------------------------------------------------------------
+
+export type PanelVariant = 'default' | 'outlined' | 'filled';
+
+export interface PanelsProps {
+	/** Optional panel heading rendered above the body. */
+	title?: string;
+	/** Visual variant. Default: `'default'`. */
+	variant?: PanelVariant;
+	/** Additional class names to append. */
+	class?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Sidebar
+// ---------------------------------------------------------------------------
+
+export interface SidebarLink {
+	type: 'link';
+	/** Display label. */
+	label: string;
+	/** Destination URL. */
+	href: string;
+	/** Optional short badge label rendered to the right of the link. */
+	badge?: { text: string; variant?: 'default' | 'note' | 'tip' | 'danger' | 'success' };
+	/** Mark link visible with muted styling (e.g. drafts). */
+	muted?: boolean;
+}
+
+export interface SidebarGroupEntry {
+	type: 'group';
+	/** Display label for the group header. */
+	label: string;
+	/** Child entries; may be nested further. */
+	children: SidebarEntry[];
+	/** Default collapsed state (user can toggle). Default: `false`. */
+	collapsed?: boolean;
+	/**
+	 * When set, the group header is a single `<a>` that both navigates to
+	 * the index page and toggles the group's expand/collapse state. When
+	 * unset, the whole header is a pure toggle.
+	 */
+	href?: string;
+}
+
+/**
+ * Non-interactive label above a flat list of child entries. Used for
+ * shallow groupings (<3 children without an index page) where a toggle
+ * would be more friction than it's worth.
+ */
+export interface SidebarSection {
+	type: 'section';
+	/** Display label for the section header. */
+	label: string;
+	/** Child entries (typically links, rarely nested). */
+	children: SidebarEntry[];
+}
+
+export type SidebarEntry = SidebarLink | SidebarGroupEntry | SidebarSection;
+
+export interface SidebarAnchor {
+	/** Display label for the anchor link. */
+	label: string;
+	/** Destination URL (may be external). */
+	href: string;
+	/** Icon name from the `Icon` component (e.g. `'github'`, `'discord'`). */
+	icon?: string;
+	/** Link target. Defaults to `'_self'`. Use `'_blank'` for external links. */
+	target?: '_blank' | '_self';
+	/** Optional small badge text (e.g. `'New'`, `'v2'`). */
+	badge?: string;
+}
+
+export interface SidebarProps {
+	/** Flat-tree navigation entries. */
+	items: SidebarEntry[];
+	/** Current pathname; used for active-link highlighting. */
+	currentPath?: string;
+	/** Optional accessible label for the nav; defaults to `'Primary'`. */
+	label?: string;
+	/** Additional class names. */
+	class?: string;
+	/**
+	 * Version list for the version switcher. Rendered at the top of the
+	 * sidebar, below the logo / site title. Omit (or pass an empty array)
+	 * to hide the switcher entirely.
+	 */
+	versions?: DocVersion[];
+	/**
+	 * Persistent anchor links pinned to the bottom of the sidebar,
+	 * separated from nav entries by a thin rule. Typically used for
+	 * external resources (GitHub, Discord, Changelog, etc.) or key
+	 * internal pages.
+	 */
+	anchors?: SidebarAnchor[];
+}
+
+// ---------------------------------------------------------------------------
+// SkipLink
+// ---------------------------------------------------------------------------
+
+export interface SkipLinkProps {
+	/** Target element id to skip to. Defaults to `publier-main`. */
+	targetId?: string;
+	/** Link label. Defaults to `Skip to content`. */
+	label?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Steps
+// ---------------------------------------------------------------------------
+
+export interface StepsProps {
+	/** Starting number (1 by default). */
+	start?: number;
+	/** Additional class names to append. */
+	class?: string;
+}
+
+// ---------------------------------------------------------------------------
+// TableOfContents
+// ---------------------------------------------------------------------------
+
+export interface TocHeading {
+	/** URL fragment / `id` attribute of the heading element. */
+	slug: string;
+	/** Display text. */
+	text: string;
+	/** Heading level (2..6 typically; 1 is page title and usually excluded). */
+	depth: number;
+}
+
+export interface TableOfContentsProps {
+	/** Ordered headings to render; caller decides filtering (`minDepth` / `maxDepth`). */
+	headings: TocHeading[];
+	/** Heading label (visually shown above the list). Default: `'On this page'`. */
+	label?: string;
+	/** Minimum depth to indent from (subtracted from each entry's depth). Default: `2`. */
+	minDepth?: number;
+	/** Additional class names. */
+	class?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Tile / TileGrid
+// ---------------------------------------------------------------------------
+
+export interface TileProps {
+	/** Tile heading text. Required. */
+	title: string;
+	/** Optional description rendered below the title. */
+	description?: string;
+	/** When provided the entire tile surface becomes a link. */
+	href?: string;
+	/** Additional class names to append. */
+	class?: string;
+}
+
+export interface TileGridProps {
+	/** Minimum column width before the grid auto-fills another column. Defaults to `'200px'`. */
+	minColumnWidth?: string;
+	/** Additional class names to append. */
+	class?: string;
+}
+
+// ---------------------------------------------------------------------------
+// TopNav / TopNavMobile
+// ---------------------------------------------------------------------------
+
+export interface TopNavProps {
+	/** Variant name from `publier.config.yaml` nav block. Default: `"default"`. */
+	variant?: string;
+	/** Current page path for active highlighting. Pass `Astro.url.pathname`. */
+	currentPath?: string;
+}
+
+export interface TopNavMobileProps {
+	variant?: string;
+	currentPath?: string;
+}
+
+// ---------------------------------------------------------------------------
+// UpdateBadge
+// ---------------------------------------------------------------------------
+
+export type UpdateBadgeType = 'new' | 'improved' | 'fixed' | 'deprecated' | 'breaking';
+
+export interface UpdateBadgeProps {
+	/** Semantic change type. Required. */
+	type: UpdateBadgeType;
+	/** Optional version string rendered adjacent to the type badge. */
+	version?: string;
+	/** Additional class names to append to the wrapper. */
+	class?: string;
+}
+
+// ---------------------------------------------------------------------------
+// VersionSwitcher
+// ---------------------------------------------------------------------------
+
+export interface DocVersion {
+	/** Display label, e.g. "v2.0" or "latest". */
+	label: string;
+	/** Root path for this version, e.g. "/v2" or "/". */
+	path: string;
+	/** Optional semantic badge shown next to the label. */
+	badge?: 'stable' | 'beta' | 'deprecated' | 'legacy';
+	/** Which version is selected by default when no path match is found. */
+	default?: boolean;
+}
+
+export interface VersionSwitcherProps {
+	/** List of available versions to present. */
+	versions: DocVersion[];
+	/** Current page pathname. Used to detect the active version via prefix matching. */
+	currentPath?: string;
+}

package/src/components/ui/blur-image.astro

@@ -0,0 +1,60 @@
+---
+interface Props {
+	src: string;
+	alt: string;
+	width?: number;
+	height?: number;
+	class?: string;
+}
+
+const { src, alt, width, height, class: cls } = Astro.props;
+
+const classes = ['publier-blur-image', cls].filter(Boolean).join(' ');
+---
+
+<img
+	src={src}
+	alt={alt}
+	width={width}
+	height={height}
+	loading="lazy"
+	data-publier-blur-image
+	class={classes}
+/>
+
+<style>
+	.publier-blur-image {
+		filter: blur(12px) grayscale(0.6);
+		transform: scale(1.02);
+		transition: filter 500ms ease, transform 500ms ease;
+	}
+	.publier-blur-image[data-loaded="1"] {
+		filter: none;
+		transform: none;
+	}
+	@media (prefers-reduced-motion: reduce) {
+		.publier-blur-image {
+			transition: none;
+		}
+	}
+</style>
+
+<script>
+	function wire() {
+		const imgs = document.querySelectorAll<HTMLImageElement>(
+			'img[data-publier-blur-image]:not([data-wired])',
+		);
+		for (const img of imgs) {
+			img.dataset.wired = '1';
+			if (img.complete && img.naturalWidth > 0) {
+				img.dataset.loaded = '1';
+			} else {
+				img.addEventListener('load', () => {
+					img.dataset.loaded = '1';
+				}, { once: true });
+			}
+		}
+	}
+	wire();
+	document.addEventListener('astro:page-load', wire);
+</script>

package/src/components/ui/changelog-entry.astro

@@ -0,0 +1,56 @@
+---
+type ChangelogEntryType = 'feature' | 'fix' | 'breaking' | 'security' | 'deprecation';
+
+interface Props {
+	date: string;
+	version?: string;
+	type?: ChangelogEntryType;
+	tags?: string[];
+	title: string;
+}
+
+const TYPE_BADGE: Record<ChangelogEntryType, string> = {
+	feature: 'badge-primary',
+	fix: 'badge-success',
+	breaking: 'badge-error',
+	security: 'badge-warning',
+	deprecation: 'badge-ghost',
+};
+
+const { date, version, type, tags, title } = Astro.props;
+const displayTags = tags ?? (type ? [type] : []);
+---
+
+<div class="relative py-10" style="grid-template-columns: 10rem 1fr; display: grid">
+	
+	<div class="pr-6 pt-0.5 text-right">
+		<time datetime={date} class="block text-sm font-semibold text-primary leading-snug">
+			{date}
+		</time>
+		{version && (
+			<span class="mt-1.5 inline-block text-xs font-mono text-base-content/60">{version}</span>
+		)}
+		{displayTags.length > 0 && (
+			<ul class="mt-2 flex flex-col items-end gap-1.5 list-none p-0 m-0">
+				{displayTags.map((tag) => (
+					<li>
+						<span class={`badge ${TYPE_BADGE[tag as ChangelogEntryType] ?? 'badge-ghost'}`}>
+							{tag}
+						</span>
+					</li>
+				))}
+			</ul>
+		)}
+	</div>
+
+	
+	<div class="absolute top-0 bottom-0 w-px bg-base-300" style="left: 10rem" aria-hidden="true" />
+
+	
+	<article class="pl-10">
+		<h3 class="text-lg font-semibold text-base-content mb-3 leading-snug">{title}</h3>
+		<div class="prose prose-sm text-base-content/80 max-w-none">
+			<slot />
+		</div>
+	</article>
+</div>

package/src/components/ui/cta-band.astro

@@ -0,0 +1,30 @@
+---
+export type CtaBandVariant = 'primary' | 'muted';
+
+interface Props {
+	title: string;
+	description?: string;
+	primaryCta: { label: string; href: string };
+	secondaryCta?: { label: string; href: string };
+	variant?: CtaBandVariant;
+}
+
+const { title, description, primaryCta, secondaryCta, variant = 'primary' } = Astro.props;
+
+const bgCls = variant === 'primary' ? 'bg-primary text-primary-content' : 'bg-base-200 text-base-content';
+const primaryBtnCls = variant === 'primary' ? 'btn btn-neutral' : 'btn btn-primary';
+const secondaryBtnCls = variant === 'primary' ? 'btn btn-outline btn-neutral' : 'btn btn-outline';
+---
+
+<section class={`${bgCls} py-14 md:py-20`}>
+	<div class="max-w-3xl mx-auto px-6 text-center">
+		<h2 class="text-3xl md:text-4xl font-bold">{title}</h2>
+		{description && <p class="mt-3 text-lg opacity-90">{description}</p>}
+		<div class="mt-7 flex flex-wrap justify-center gap-3">
+			<a class={primaryBtnCls} href={primaryCta.href}>{primaryCta.label}</a>
+			{secondaryCta && (
+				<a class={secondaryBtnCls} href={secondaryCta.href}>{secondaryCta.label}</a>
+			)}
+		</div>
+	</div>
+</section>

package/src/components/ui/feature-grid.astro

@@ -0,0 +1,38 @@
+---
+interface Item {
+	icon?: string;
+	title: string;
+	description: string;
+	href?: string;
+}
+
+interface Props {
+	items: Item[];
+	columns?: 2 | 3 | 4;
+}
+
+const { items, columns = 3 } = Astro.props;
+
+const colCls = columns === 2
+	? 'md:grid-cols-2'
+	: columns === 4
+		? 'md:grid-cols-2 lg:grid-cols-4'
+		: 'md:grid-cols-2 lg:grid-cols-3';
+---
+
+<div class={`grid gap-4 ${colCls}`}>
+	{items.map((item) => (
+		<article class="card bg-base-100 border border-base-300 hover:shadow-md transition-shadow relative">
+			<div class="card-body">
+				{item.icon && <div class="text-3xl leading-none" aria-hidden="true">{item.icon}</div>}
+				<h3 class="card-title text-lg text-base-content">{item.title}</h3>
+				<p class="text-base-content/70">{item.description}</p>
+				{item.href && (
+					<a class="absolute inset-0" href={item.href} aria-label={item.title}>
+						<span class="sr-only">Learn more about {item.title}</span>
+					</a>
+				)}
+			</div>
+		</article>
+	))}
+</div>