@levino/shipyard-base 0.6.2 → 0.6.3-rc-20260113205743

package/astro/components/DeprecationBanner.astro

@@ -0,0 +1,104 @@
+---
+/**
+ * Deprecation banner component that displays a warning when viewing deprecated docs.
+ * Shows a prominent alert with a link to the same page in the latest version.
+ * The banner can be dismissed but will reappear on navigation.
+ */
+
+interface Props {
+  /** The deprecated version being viewed */
+  version: string
+  /** Human-readable label for the deprecated version */
+  label?: string
+  /** The current/latest version to link to */
+  currentVersion: string
+  /** Human-readable label for the current version */
+  currentVersionLabel?: string
+  /** URL to the same page in the latest version */
+  latestVersionUrl: string
+  /** Additional CSS classes */
+  class?: string
+}
+
+const {
+  version,
+  label,
+  currentVersion,
+  currentVersionLabel,
+  latestVersionUrl,
+  class: className,
+} = Astro.props
+
+const displayVersion = label ?? version
+const displayCurrentVersion = currentVersionLabel ?? currentVersion
+---
+
+<div
+  class:list={['deprecation-banner', className]}
+  data-testid="deprecation-banner"
+  role="alert"
+>
+  <div class="alert alert-warning shadow-lg">
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      class="h-6 w-6 shrink-0 stroke-current"
+      fill="none"
+      viewBox="0 0 24 24"
+    >
+      <path
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        stroke-width="2"
+        d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"
+      />
+    </svg>
+    <div class="flex-1">
+      <h3 class="font-bold">Outdated Documentation</h3>
+      <p class="text-sm">
+        You are viewing documentation for <strong>{displayVersion}</strong>, which is no longer
+        maintained.
+        <a href={latestVersionUrl} class="link link-hover font-medium">
+          View the latest version ({displayCurrentVersion})
+        </a>
+      </p>
+    </div>
+    <button
+      type="button"
+      class="btn btn-ghost btn-sm btn-circle"
+      aria-label="Dismiss banner"
+      data-dismiss-banner
+    >
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        class="h-5 w-5"
+        fill="none"
+        viewBox="0 0 24 24"
+        stroke="currentColor"
+      >
+        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
+      </svg>
+    </button>
+  </div>
+</div>
+
+<script>
+  // Handle dismiss button click
+  // The banner will reappear on navigation (page reload)
+  function initDeprecationBanner() {
+    const banners = document.querySelectorAll('.deprecation-banner')
+    banners.forEach((banner) => {
+      const dismissBtn = banner.querySelector('[data-dismiss-banner]')
+      if (dismissBtn) {
+        dismissBtn.addEventListener('click', () => {
+          banner.classList.add('hidden')
+        })
+      }
+    })
+  }
+
+  // Initialize on page load
+  initDeprecationBanner()
+
+  // Re-initialize on Astro view transitions
+  document.addEventListener('astro:page-load', initDeprecationBanner)
+</script>

package/astro/components/GlobalDesktopNavigation.astro

@@ -70,6 +70,7 @@ const { brand, navigation, showBrand = false } = Astro.props as Props
         )
       }
     </ul>
+    <slot name="navbarExtra" />
     <ThemeToggle class="btn btn-ghost btn-circle" />
     <LanguageSwitcher variant="dropdown" />
   </div>

package/astro/components/SidebarNavigation.astro

@@ -36,6 +36,7 @@ const withLocale = (path: string) =>
         )
       }
     </li>
+    <slot name="sidebarExtra" />
     <LanguageSwitcher variant="list" />
     <li class="flex flex-row items-center gap-2 px-4 py-2">
       <span class="text-sm opacity-70">Theme</span>

package/astro/components/VersionBadge.astro

@@ -0,0 +1,116 @@
+---
+/**
+ * Version badge component that displays version status inline.
+ * Shows badges for stable, deprecated, latest, or unreleased versions.
+ * Can be used to indicate the version status at the top of docs pages.
+ */
+
+interface Props {
+  /** The version identifier (e.g., "v1.0", "v2.0") */
+  version: string
+  /** Human-readable label for display (defaults to version) */
+  label?: string
+  /** The stable version for comparison */
+  stableVersion?: string
+  /** The current/latest version for comparison */
+  currentVersion?: string
+  /** List of deprecated versions */
+  deprecatedVersions?: string[]
+  /** Banner type for this version (from config) */
+  banner?: 'unreleased' | 'unmaintained'
+  /** Whether this is the latest alias */
+  isLatestAlias?: boolean
+  /** Additional CSS classes */
+  class?: string
+  /** Size variant: 'sm' for small, 'md' for medium, 'lg' for large */
+  size?: 'sm' | 'md' | 'lg'
+}
+
+const {
+  version,
+  label,
+  stableVersion,
+  currentVersion,
+  deprecatedVersions = [],
+  banner,
+  isLatestAlias = false,
+  class: className,
+  size = 'md',
+} = Astro.props
+
+// Determine badge type based on version status
+type BadgeType = 'stable' | 'latest' | 'deprecated' | 'unreleased' | null
+
+const getBadgeType = (): BadgeType => {
+  // Unreleased takes precedence
+  if (banner === 'unreleased') {
+    return 'unreleased'
+  }
+  // Deprecated/unmaintained
+  if (banner === 'unmaintained' || deprecatedVersions.includes(version)) {
+    return 'deprecated'
+  }
+  // Stable version
+  if (stableVersion && version === stableVersion) {
+    return 'stable'
+  }
+  // Latest/current version (and not stable, so show as latest)
+  if (
+    currentVersion &&
+    version === currentVersion &&
+    version !== stableVersion
+  ) {
+    return 'latest'
+  }
+  // If viewing via latest alias
+  if (isLatestAlias) {
+    return 'latest'
+  }
+  return null
+}
+
+const badgeType = getBadgeType()
+const displayLabel = label ?? version
+
+// Badge styling based on type
+const getBadgeClasses = () => {
+  const sizeClass = {
+    sm: 'badge-sm',
+    md: '',
+    lg: 'badge-lg',
+  }[size]
+
+  const typeClass = {
+    stable: 'badge-success',
+    latest: 'badge-primary',
+    deprecated: 'badge-warning',
+    unreleased: 'badge-info',
+  }[badgeType ?? 'stable']
+
+  return ['badge', sizeClass, typeClass, className].filter(Boolean).join(' ')
+}
+
+const getBadgeLabel = () => {
+  switch (badgeType) {
+    case 'stable':
+      return 'Stable'
+    case 'latest':
+      return 'Latest'
+    case 'deprecated':
+      return 'Deprecated'
+    case 'unreleased':
+      return 'Unreleased'
+    default:
+      return null
+  }
+}
+
+const badgeLabel = getBadgeLabel()
+---
+
+{badgeLabel && (
+  <span class={getBadgeClasses()} data-testid="version-badge">
+    <span class="sr-only">Version {displayLabel} - </span>
+    {badgeLabel}
+  </span>
+)}

package/astro/components/VersionSelector.astro

@@ -0,0 +1,207 @@
+---
+/**
+ * Version selector component that displays available documentation versions.
+ * Allows users to switch between different versions of the documentation.
+ */
+
+interface VersionInfo {
+  /** The version identifier (e.g., "v1.0", "v2.0") */
+  version: string
+  /** Human-readable label for display */
+  label?: string
+  /** Path segment used in URLs */
+  path?: string
+  /** Banner type for this version */
+  banner?: 'unreleased' | 'unmaintained'
+}
+
+interface Props {
+  /** All available versions */
+  versions: VersionInfo[]
+  /** The current version being viewed */
+  currentVersion: string
+  /** The stable version (for badge display) */
+  stableVersion?: string
+  /** List of deprecated version identifiers */
+  deprecatedVersions?: string[]
+  /** Additional CSS classes */
+  class?: string
+  /** Variant: 'dropdown' for navbar, 'list' for sidebar */
+  variant?: 'dropdown' | 'list'
+}
+
+const {
+  versions,
+  currentVersion,
+  stableVersion,
+  deprecatedVersions = [],
+  class: className,
+  variant = 'dropdown',
+} = Astro.props
+
+const currentPath = Astro.url.pathname
+
+// Get display label for current version
+const currentVersionInfo = versions.find(
+  (v) => v.version === currentVersion || v.path === currentVersion,
+)
+const currentLabel = currentVersionInfo?.label ?? currentVersion
+
+// Build the path for other versions by replacing the current version in the URL
+const getVersionPath = (targetVersion: VersionInfo) => {
+  const targetPath = targetVersion.path ?? targetVersion.version
+  const currentVersionPath = currentVersionInfo?.path ?? currentVersion
+
+  // Replace the version segment in the current URL
+  // This handles both /docs/v1/page and /en/docs/v1/page patterns
+  return currentPath.replace(
+    new RegExp(`/${escapeRegex(currentVersionPath)}/`),
+    `/${targetPath}/`,
+  )
+}
+
+// Escape special regex characters
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+// Helper to get badge info for a version
+function getVersionBadge(version: VersionInfo): {
+  type: 'stable' | 'deprecated' | 'unreleased' | null
+  label: string
+} | null {
+  if (version.banner === 'unreleased') {
+    return { type: 'unreleased', label: 'Unreleased' }
+  }
+  if (
+    version.banner === 'unmaintained' ||
+    deprecatedVersions.includes(version.version)
+  ) {
+    return { type: 'deprecated', label: 'Deprecated' }
+  }
+  if (stableVersion && version.version === stableVersion) {
+    return { type: 'stable', label: 'Stable' }
+  }
+  return null
+}
+
+const hasMultipleVersions = versions.length > 1
+---
+
+{hasMultipleVersions && variant === 'dropdown' && (
+  <div class:list={['dropdown dropdown-end', className]} data-testid="version-selector">
+    <div tabindex="0" role="button" class="btn btn-ghost gap-1">
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        class="h-5 w-5"
+        fill="none"
+        viewBox="0 0 24 24"
+        stroke="currentColor"
+      >
+        <path
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          stroke-width="2"
+          d="M7 7h.01M7 3h5c.512 0 1.024.195 1.414.586l7 7a2 2 0 010 2.828l-7 7a2 2 0 01-2.828 0l-7-7A2 2 0 013 12V7a4 4 0 014-4z"
+        />
+      </svg>
+      <span class="hidden sm:inline">{currentLabel}</span>
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        class="h-4 w-4"
+        fill="none"
+        viewBox="0 0 24 24"
+        stroke="currentColor"
+      >
+        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7" />
+      </svg>
+    </div>
+    <ul
+      tabindex="0"
+      class="dropdown-content menu rounded-box z-50 mt-3 w-52 bg-base-100 p-2 shadow"
+    >
+      {versions.map((version) => {
+        const badge = getVersionBadge(version)
+        const isActive = version.version === currentVersion || version.path === currentVersion
+        return (
+          <li>
+            <a
+              href={getVersionPath(version)}
+              class:list={[{ active: isActive }]}
+            >
+              <span class="flex-1">{version.label ?? version.version}</span>
+              {badge && (
+                <span
+                  class:list={[
+                    'badge badge-sm',
+                    {
+                      'badge-success': badge.type === 'stable',
+                      'badge-warning': badge.type === 'deprecated',
+                      'badge-info': badge.type === 'unreleased',
+                    },
+                  ]}
+                >
+                  {badge.label}
+                </span>
+              )}
+            </a>
+          </li>
+        )
+      })}
+    </ul>
+  </div>
+)}
+
+{hasMultipleVersions && variant === 'list' && (
+  <li class={className} data-testid="version-selector">
+    <details>
+      <summary class="gap-2">
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          class="h-5 w-5"
+          fill="none"
+          viewBox="0 0 24 24"
+          stroke="currentColor"
+        >
+          <path
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            stroke-width="2"
+            d="M7 7h.01M7 3h5c.512 0 1.024.195 1.414.586l7 7a2 2 0 010 2.828l-7 7a2 2 0 01-2.828 0l-7-7A2 2 0 013 12V7a4 4 0 014-4z"
+          />
+        </svg>
+        {currentLabel}
+      </summary>
+      <ul>
+        {versions.map((version) => {
+          const badge = getVersionBadge(version)
+          const isActive = version.version === currentVersion || version.path === currentVersion
+          return (
+            <li>
+              <a
+                href={getVersionPath(version)}
+                class:list={[{ active: isActive }]}
+              >
+                <span class="flex-1">{version.label ?? version.version}</span>
+                {badge && (
+                  <span
+                    class:list={[
+                      'badge badge-sm',
+                      {
+                        'badge-success': badge.type === 'stable',
+                        'badge-warning': badge.type === 'deprecated',
+                        'badge-info': badge.type === 'unreleased',
+                      },
+                    ]}
+                  >
+                    {badge.label}
+                  </span>
+                )}
+              </a>
+            </li>
+          )
+        })}
+      </ul>
+    </details>
+  </li>
+)}

package/astro/components/index.ts

@@ -1,8 +1,10 @@
 export { default as Admonition } from './Admonition.astro'
 export { default as AnnouncementBar } from './AnnouncementBar.astro'
 export { default as Breadcrumbs } from './Breadcrumbs.astro'
+export { default as DeprecationBanner } from './DeprecationBanner.astro'
 export { default as Footer } from './Footer.astro'
 export { default as GlobalDesktopNavigation } from './GlobalDesktopNavigation.astro'
+export { default as LanguageSwitcher } from './LanguageSwitcher.astro'
 export { default as LocalNavigation } from './LocalNavigation.astro'
 export { default as Npm2YarnScript } from './Npm2YarnScript.astro'
 export { default as SidebarElement } from './SidebarElement.astro'
@@ -11,3 +13,5 @@ export { default as TabItem } from './TabItem.astro'
 export { default as TableOfContents } from './TableOfContents.astro'
 export { default as Tabs } from './Tabs.astro'
 export { default as ThemeToggle } from './ThemeToggle.astro'
+export { default as VersionBadge } from './VersionBadge.astro'
+export { default as VersionSelector } from './VersionSelector.astro'

package/astro/layouts/Page.astro

@@ -116,7 +116,9 @@ const renderScriptAttributes = (script: Script) => {
             showBrand={!props.sidebarNavigation}
             brand={config.brand}
             navigation={navigation}
-          />
+          >
+            <slot name="navbarExtra" slot="navbarExtra" />
+          </GlobalDesktopNavigation>
           <div class="grow">
             <div class="mx-auto px-4">
               <slot />
@@ -134,7 +136,9 @@ const renderScriptAttributes = (script: Script) => {
             brand={config.brand}
             global={navigation}
             local={props.sidebarNavigation}
-          />
+          >
+            <slot name="sidebarExtra" slot="sidebarExtra" />
+          </SidebarNavigation>
         </div>
       </div>
     </div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levino/shipyard-base",
-  "version": "0.6.2",
+  "version": "0.6.3-rc-20260113205743",
   "description": "Core layouts, components, and configuration for shipyard - a composable page builder for Astro",
   "keywords": [
     "astro",

package/src/index.ts

@@ -1,5 +1,8 @@
 import { fileURLToPath } from 'node:url'
 import type { AstroIntegration } from 'astro'
+import remarkDirective from 'remark-directive'
+import { remarkAdmonitions } from './remark/remarkAdmonitions'
+import { remarkNpm2Yarn } from './remark/remarkNpm2Yarn'
 import type { Config } from './schemas/config'
 import { checkLinks, reportBrokenLinks } from './tools/linkChecker'
 
@@ -39,6 +42,9 @@ export default (config: Config): AstroIntegration => {
         } as Record<string, string | undefined>
 
         updateConfig({
+          markdown: {
+            remarkPlugins: [remarkDirective, remarkAdmonitions, remarkNpm2Yarn],
+          },
           vite: {
             plugins: [
               {

package/src/remark/index.ts

@@ -1,17 +1,9 @@
 /**
  * Remark plugins for shipyard markdown processing.
  *
- * @example
- * ```ts
- * import remarkDirective from 'remark-directive'
- * import { remarkAdmonitions } from '@levino/shipyard-base/remark'
- *
- * export default defineConfig({
- *   markdown: {
- *     remarkPlugins: [remarkDirective, remarkAdmonitions],
- *   },
- * })
- * ```
+ * Note: These plugins are automatically registered by the shipyard integration.
+ * You don't need to configure them manually. They are exported here for
+ * advanced use cases where you need direct access to the plugins.
  */
 
 // Re-export remark-directive for convenience

package/src/remark/remarkAdmonitions.ts

@@ -41,7 +41,10 @@ const getDefaultTitle = (type: AdmonitionType): string => {
 /**
  * Remark plugin to transform container directives into admonitions.
  *
- * This plugin works with remark-directive to transform:
+ * This plugin is automatically registered by the shipyard integration.
+ * You don't need to configure it manually.
+ *
+ * It works with remark-directive to transform:
  * ```markdown
  * :::note
  * This is a note
@@ -53,18 +56,6 @@ const getDefaultTitle = (type: AdmonitionType): string => {
  * ```
  *
  * Into properly structured admonition HTML.
- *
- * @example
- * ```ts
- * import remarkDirective from 'remark-directive'
- * import { remarkAdmonitions } from '@levino/shipyard-base/remark'
- *
- * export default defineConfig({
- *   markdown: {
- *     remarkPlugins: [remarkDirective, remarkAdmonitions],
- *   },
- * })
- * ```
  */
 export const remarkAdmonitions: Plugin<[], Root> = () => {
   return (tree: Root) => {