fix(docs): include components at different version stages in versioned docs

docs/guides/upgrade-guide.md

@@ -231,6 +231,18 @@ type: embed
 
 ```
 
+### DateInput / DateInput2
+
+**Short version:** Use [`DateInput`](/v11_7/DateInput). Forget `DateInput2` exists.
+
+**The full story:** The original `DateInput` had a complex API — you had to manually wire up calendar navigation, day rendering, and date parsing. We wanted to simplify it but couldn't without breaking changes, so we released `DateInput2` as a drop-in alternative with a much simpler API.
+
+Now that InstUI supports component versioning, we no longer need the separate `DateInput2` name. Instead:
+
+- **[DateInput v2](/v11_7/DateInput)** (from v11.7) — the recommended version. Same component that was previously `DateInput2`, same API. **This is the only version that will receive the new theming.**
+- **[DateInput v1](/v11_6/DateInput)** (up to v11.6) — the original component. **Deprecated.** Does not support the new theming system.
+- **[DateInput2 v1](/v11_6/DateInput2)** — **Deprecated.** Will not get a v2 and does not support the new theming system. If you're using `DateInput2`, switch your import to `DateInput` (from v11.7) — the API is identical, no other code changes needed.
+
 ### ColorPicker
 
 ```js

packages/__docs__/buildScripts/DataTypes.mts

@@ -146,7 +146,7 @@ type MainDocsData = {
 
 type VersionMapEntry = {
   exportLetter: string
-  componentVersion: string
+  componentVersions: string[]
 }
 
 type VersionMap = {

packages/__docs__/buildScripts/utils/buildVersionMap.mts

@@ -92,8 +92,8 @@ export async function buildVersionMap(
         continue
       }
 
-      // Resolve the component version from the source export file
-      const componentVersion = resolveComponentVersion(
+      // Resolve all component versions from the source export file
+      const componentVersions = resolveComponentVersions(
         pkgDir,
         exportLetter,
         pkgShortName
@@ -104,7 +104,7 @@ export async function buildVersionMap(
       }
       mapping[libVersion][pkgShortName] = {
         exportLetter,
-        componentVersion
+        componentVersions
       }
     }
   }
@@ -162,18 +162,20 @@ export function isDocIncludedInVersion(
     return componentVersion === 'v1'
   }
 
-  return componentVersion === entry.componentVersion
+  return entry.componentVersions.includes(componentVersion)
 }
 
 /**
  * Reads the source export file (e.g. src/exports/a.ts) and parses imports
- * to determine which component version directory it maps to (v1 or v2).
+ * to determine which component version directories it maps to (v1, v2, etc.).
+ * A single export file may reference multiple versions when a package contains
+ * components at different migration stages (e.g. DateInput/v2 + DateInput2/v1).
  */
-function resolveComponentVersion(
+function resolveComponentVersions(
   pkgDir: string,
   exportLetter: string,
   pkgShortName: string
-): string {
+): string[] {
   const exportFilePath = path.join(
     pkgDir,
     'src',
@@ -190,20 +192,24 @@ function resolveComponentVersion(
 
   const content = fs.readFileSync(exportFilePath, 'utf-8')
 
-  // Match patterns like:
+  // Match all patterns like:
   //   from '../ComponentName/v2'
   //   from '../ComponentName/v1/SubComponent'
-  const versionMatch = content.match(
-    /from\s+['"]\.\.\/[^/]+\/(v\d+)(?:\/|['"])/
-  )
-  if (versionMatch) {
-    return versionMatch[1]
+  const versionRegex = /from\s+['"]\.\.\/[^/]+\/(v\d+)(?:\/|['"])/g
+  const versions = new Set<string>()
+  let match
+  while ((match = versionRegex.exec(content)) !== null) {
+    versions.add(match[1])
   }
 
-  throw new Error(
-    `[buildVersionMap] Could not resolve component version from ${exportFilePath} (${pkgShortName}). ` +
-    `Ensure the file has an import like: from '../ComponentName/v1'`
-  )
+  if (versions.size === 0) {
+    throw new Error(
+      `[buildVersionMap] Could not resolve component version from ${exportFilePath} (${pkgShortName}). ` +
+      `Ensure the file has an import like: from '../ComponentName/v1'`
+    )
+  }
+
+  return Array.from(versions)
 }
 
 /**

packages/__docs__/src/compileMarkdown.tsx

@@ -39,7 +39,7 @@ import { Playground } from './Playground'
 import { compileAndRenderExample } from './compileAndRenderExample'
 import { Heading } from './Heading'
 import { Link } from './Link'
-import { navigateTo } from './navigationUtils'
+import { navigateTo, MINOR_VERSION_REGEX } from './navigationUtils'
 
 type CodeData = {
   code: string
@@ -286,7 +286,21 @@ const renderer = (title: string) => ({
           return
         }
         e.preventDefault()
-        navigateTo(href)
+
+        // Markdown links can point to a specific version of a component,
+        // e.g. href="/v11_7/DateInput". navigateTo() expects the page
+        // name and version as separate arguments, so we need to split
+        // them apart. Plain links like "DateInput" are passed through
+        // as-is.
+        const path = href.replace(/^\/+/, '') // "/v11_7/DateInput" -> "v11_7/DateInput"
+        const [first, second] = path.split('/')
+        const isVersionedLink = MINOR_VERSION_REGEX.test(first) && second
+
+        if (isVersionedLink) {
+          navigateTo(second, { minorVersion: first })
+        } else {
+          navigateTo(href)
+        }
       }}
     >
       {text}

packages/ui-date-input/README.md

@@ -10,7 +10,8 @@ A date input component.
 
 The `ui-date-input` package contains the following:
 
-- [DateInput](DateInput)
+- [DateInput](DateInput) — the recommended date input component
+- [DateInput2](DateInput2) — deprecated, use `DateInput` instead
 
 ### Installation
 

packages/ui-date-input/src/DateInput/v1/README.md

@@ -2,7 +2,15 @@
 describes: DateInput
 ---
 
-> _Note:_ we recommend to update to the new [`DateInput2`](/#DateInput2) which is easier to configure for developers, has a better UX, better accessibility features and a year picker. `DateInput` will be deprecated in the future.
+> **Deprecated:** This version of `DateInput` is deprecated. Please use the latest version of [`DateInput`](/v11_7/DateInput) which offers easier configuration, better UX, improved accessibility, and a year picker.
+
+### DateInput versions at a glance
+
+| Version                                    | API                          | Theming          | Accessibility   | Status          |
+| :----------------------------------------- | :--------------------------- | :--------------- | :-------------- | :-------------- |
+| [v11.6 DateInput](/v11_6/DateInput) (this) | Old (manual calendar wiring) | Old theming only | Has a11y issues | **Deprecated**  |
+| [v11.6 DateInput2](/v11_6/DateInput2)      | New (simple)                 | Old theming only | Good            | **Deprecated**  |
+| [v11.7 DateInput](/v11_7/DateInput)        | New (simple)                 | New theming      | Good            | **Recommended** |
 
 The `DateInput` component provides a visual interface for inputting date data.