@uniweb/core 0.1.16 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.1.16",
+  "version": "0.2.0",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {

package/src/block.js

@@ -10,6 +10,7 @@ import { parseContent as parseSemanticContent } from '@uniweb/semantic-parser'
 export default class Block {
   constructor(blockData, id) {
     this.id = id
+    this.stableId = blockData.stableId || null // Stable section ID for scroll targeting (from filename or frontmatter)
     // 'type' matches frontmatter convention; 'component' supported for backwards compatibility
     this.type = blockData.type || blockData.component || 'Section'
     this.Component = null

package/src/page.js

@@ -18,6 +18,7 @@ export default class Page {
     pageRight,
   ) {
     this.id = id
+    this.stableId = pageData.id || null // Stable page ID for page: links (from page.yml)
     this.route = pageData.route
     this.isIndex = pageData.isIndex || false // True if this page is the index for its parent route
     this.title = pageData.title || ''
@@ -66,6 +67,11 @@ export default class Page {
     // Dynamic route context (for pages created from dynamic routes like /blog/:slug)
     this.dynamicContext = pageData.dynamicContext || null
 
+    // Version context (for pages within versioned sections like /docs/v1/*)
+    this.version = pageData.version || null // { id, label, latest, deprecated }
+    this.versionMeta = pageData.versionMeta || null // { versions, latestId }
+    this.versionScope = pageData.versionScope || null // The route where versioning starts
+
     // Build block groups for all layout areas
     this.pageBlocks = this.buildPageBlocks(
       pageData.sections,
@@ -501,4 +507,58 @@ export default class Page {
   isActiveOrAncestor(currentRoute) {
     return this.website.isRouteActiveOrAncestor(this.route, currentRoute)
   }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Version API (for documentation pages)
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Check if this page is within a versioned section
+   * @returns {boolean}
+   */
+  isVersioned() {
+    return this.version !== null
+  }
+
+  /**
+   * Get the current version for this page
+   * @returns {Object|null} Version info { id, label, latest, deprecated } or null
+   */
+  getVersion() {
+    return this.version
+  }
+
+  /**
+   * Get all available versions for this page's scope
+   * @returns {Array} Array of version objects, or empty array
+   */
+  getVersions() {
+    return this.versionMeta?.versions || []
+  }
+
+  /**
+   * Check if this page is on the latest version
+   * @returns {boolean}
+   */
+  isLatestVersion() {
+    return this.version?.latest === true
+  }
+
+  /**
+   * Check if this page is on a deprecated version
+   * @returns {boolean}
+   */
+  isDeprecatedVersion() {
+    return this.version?.deprecated === true
+  }
+
+  /**
+   * Get URL for switching to a different version of this page
+   * @param {string} targetVersion - Target version ID (e.g., 'v1')
+   * @returns {string|null} Target URL or null if not versioned
+   */
+  getVersionUrl(targetVersion) {
+    if (!this.isVersioned()) return null
+    return this.website.getVersionUrl(targetVersion, this.route)
+  }
 }

package/src/website.js

@@ -6,26 +6,9 @@
 
 import Page from './page.js'
 
-// Common locale display names
-const LOCALE_NAMES = {
-  en: 'English',
-  es: 'Español',
-  fr: 'Français',
-  de: 'Deutsch',
-  it: 'Italiano',
-  pt: 'Português',
-  nl: 'Nederlands',
-  pl: 'Polski',
-  ru: 'Русский',
-  ja: '日本語',
-  ko: '한국어',
-  zh: '中文',
-  ar: 'العربية'
-}
-
 export default class Website {
   constructor(websiteData) {
-    const { pages = [], theme = {}, config = {}, header, footer, left, right, notFound } = websiteData
+    const { pages = [], theme = {}, config = {}, header, footer, left, right, notFound, versionedScopes = {} } = websiteData
 
     // Site metadata
     this.name = config.name || ''
@@ -86,40 +69,62 @@ export default class Website {
     // Legacy language support (for editor multilingual)
     this.activeLang = this.activeLocale
     this.langs = config.languages || this.locales.map(l => ({
-      label: l.label,
+      label: l.label || l.code,
       value: l.code
     }))
+
+    // Versioned scopes: route → { versions, latestId }
+    // Scopes are routes where versioning starts (e.g., '/docs')
+    this.versionedScopes = versionedScopes
   }
 
   /**
    * Build locales list from config
+   * Supports both string codes and objects: ['es', 'fr'] or [{code: 'es', label: 'Español'}]
+   * Labels are passed through if provided; otherwise only code is returned.
+   * Use kit's getLocaleLabel() for display names.
    * @private
    */
   buildLocalesList(config) {
     const defaultLocale = config.defaultLanguage || 'en'
     const i18nLocales = config.i18n?.locales || []
 
-    // Start with default locale
-    const allLocaleCodes = [defaultLocale]
+    // Normalize input: convert strings to objects, keep objects as-is
+    const normalizeLocale = (locale) => {
+      if (typeof locale === 'string') {
+        return { code: locale }
+      }
+      // Object with code and optional label
+      return { code: locale.code, ...(locale.label && { label: locale.label }) }
+    }
+
+    // Start with default locale (may not be in i18nLocales)
+    const localeMap = new Map()
+    localeMap.set(defaultLocale, { code: defaultLocale })
 
-    // Add translated locales (avoiding duplicates)
+    // Add i18n locales (may include objects with labels)
     for (const locale of i18nLocales) {
-      if (!allLocaleCodes.includes(locale)) {
-        allLocaleCodes.push(locale)
+      const normalized = normalizeLocale(locale)
+      // Merge with existing (to preserve labels if default locale also in i18n with label)
+      if (localeMap.has(normalized.code)) {
+        const existing = localeMap.get(normalized.code)
+        localeMap.set(normalized.code, { ...existing, ...normalized })
+      } else {
+        localeMap.set(normalized.code, normalized)
       }
     }
 
-    // Build full locale objects
-    return allLocaleCodes.map(code => ({
-      code,
-      label: LOCALE_NAMES[code] || code.toUpperCase(),
-      isDefault: code === defaultLocale
+    // Build final array with isDefault flag
+    return Array.from(localeMap.values()).map(locale => ({
+      ...locale,
+      isDefault: locale.code === defaultLocale
     }))
   }
 
   /**
    * Build parent-child relationships between pages based on route structure
    * E.g., /getting-started/installation is a child of /getting-started
+   * Also builds page ID map for makeHref() resolution
    * @private
    */
   buildPageHierarchy() {
@@ -168,6 +173,21 @@ export default class Website {
         page.children.sort((a, b) => (a.order || 0) - (b.order || 0))
       }
     }
+
+    // Build page ID map for makeHref() resolution
+    // Supports both explicit IDs and route-based lookup
+    this._pageIdMap = new Map()
+    for (const page of this.pages) {
+      // Explicit stableId takes priority (survives page reorganization)
+      if (page.stableId) {
+        this._pageIdMap.set(page.stableId, page)
+      }
+      // Route-based lookup (normalized, without leading/trailing slashes)
+      const routeId = this.normalizeRoute(page.route)
+      if (routeId && !this._pageIdMap.has(routeId)) {
+        this._pageIdMap.set(routeId, page)
+      }
+    }
   }
 
   /**
@@ -447,12 +467,46 @@ export default class Website {
 
   /**
    * Make href (for link transformation)
-   * @param {string} href
-   * @returns {string}
+   * Resolves page: references to actual routes
+   *
+   * @param {string} href - The href to transform
+   * @returns {string} Resolved href
+   *
+   * @example
+   * makeHref('page:getting-started')           // → '/docs/getting-started'
+   * makeHref('page:getting-started#install')   // → '/docs/getting-started#section-install'
+   * makeHref('page:docs/api')                  // → '/docs/api' (route-based)
+   * makeHref('/about')                         // → '/about' (passthrough)
    */
   makeHref(href) {
-    // Could add basename handling here
-    return href
+    if (!href || !href.startsWith('page:')) {
+      return href
+    }
+
+    // Parse page reference: page:pageId#sectionId
+    const withoutPrefix = href.slice(5) // Remove 'page:'
+    const [pageId, sectionId] = withoutPrefix.split('#')
+
+    // Look up page by ID (explicit or route-based)
+    const page = this._pageIdMap?.get(pageId)
+
+    if (!page) {
+      // Page not found - return original href (or could warn in dev)
+      if (typeof console !== 'undefined' && process?.env?.NODE_ENV !== 'production') {
+        console.warn(`[makeHref] Page not found: ${pageId}`)
+      }
+      return href
+    }
+
+    // Build the resolved href
+    let resolvedHref = page.route
+
+    // Add section hash if specified (with section- prefix for DOM ID)
+    if (sectionId) {
+      resolvedHref += `#section-${sectionId}`
+    }
+
+    return resolvedHref
   }
 
   /**
@@ -477,7 +531,8 @@ export default class Website {
 
   /**
    * Get all available locales
-   * @returns {Array<{code: string, label: string, isDefault: boolean}>}
+   * Label is optional - use kit's getLocaleLabel() for display names if not provided.
+   * @returns {Array<{code: string, label?: string, isDefault: boolean}>}
    */
   getLocales() {
     return this.locales
@@ -871,4 +926,170 @@ export default class Website {
     // Check if current starts with target followed by /
     return current.startsWith(target + '/')
   }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Version API (for documentation sites)
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Get all versioned scopes
+   * Returns a map of scope routes to their version metadata
+   *
+   * @returns {Object} Map of scope → { versions, latestId }
+   *
+   * @example
+   * website.getVersionedScopes()
+   * // { '/docs': { versions: [...], latestId: 'v2' } }
+   */
+  getVersionedScopes() {
+    return this.versionedScopes
+  }
+
+  /**
+   * Check if site has any versioned content
+   * @returns {boolean}
+   */
+  hasVersionedContent() {
+    return Object.keys(this.versionedScopes).length > 0
+  }
+
+  /**
+   * Get the versioned scope that contains a given route
+   * Returns the scope route if the route is within a versioned section
+   *
+   * @param {string} route - Route to check (e.g., '/docs/getting-started')
+   * @returns {string|null} The scope route (e.g., '/docs') or null
+   *
+   * @example
+   * website.getVersionScope('/docs/getting-started') // '/docs'
+   * website.getVersionScope('/about')                // null
+   */
+  getVersionScope(route) {
+    const normalizedRoute = route || ''
+
+    // Check each versioned scope to see if route falls within it
+    for (const scope of Object.keys(this.versionedScopes)) {
+      // Route matches scope exactly or is a child of scope
+      if (normalizedRoute === scope || normalizedRoute.startsWith(scope + '/')) {
+        return scope
+      }
+    }
+
+    return null
+  }
+
+  /**
+   * Check if a route is within a versioned section
+   *
+   * @param {string} route - Route to check
+   * @returns {boolean}
+   */
+  isVersionedRoute(route) {
+    return this.getVersionScope(route) !== null
+  }
+
+  /**
+   * Get version metadata for a scope
+   *
+   * @param {string} scope - The scope route (e.g., '/docs')
+   * @returns {Object|null} Version metadata { versions, latestId } or null
+   *
+   * @example
+   * website.getVersionMeta('/docs')
+   * // { versions: [{ id: 'v2', label: 'v2', latest: true }, ...], latestId: 'v2' }
+   */
+  getVersionMeta(scope) {
+    return this.versionedScopes[scope] || null
+  }
+
+  /**
+   * Get the current version for a page
+   * Returns the version object from the page's version metadata
+   *
+   * @param {Page} page - The page to check
+   * @returns {Object|null} Version object { id, label, latest, deprecated } or null
+   */
+  getPageVersion(page) {
+    return page?.version || null
+  }
+
+  /**
+   * Get available versions for a route's scope
+   *
+   * @param {string} route - Route within a versioned scope
+   * @returns {Array} Array of version objects, or empty array
+   *
+   * @example
+   * website.getVersionsForRoute('/docs/getting-started')
+   * // [{ id: 'v2', label: 'v2', latest: true }, { id: 'v1', label: 'v1' }]
+   */
+  getVersionsForRoute(route) {
+    const scope = this.getVersionScope(route)
+    if (!scope) return []
+
+    const meta = this.versionedScopes[scope]
+    return meta?.versions || []
+  }
+
+  /**
+   * Compute URL for switching to a different version
+   * Takes the current route and computes what the URL would be for another version
+   *
+   * @param {string} targetVersion - Target version ID (e.g., 'v1')
+   * @param {string} currentRoute - Current route (e.g., '/docs/getting-started')
+   * @returns {string|null} Target URL or null if not versioned
+   *
+   * @example
+   * // Current: /docs/getting-started (latest v2)
+   * website.getVersionUrl('v1', '/docs/getting-started')
+   * // → '/docs/v1/getting-started'
+   *
+   * // Current: /docs/v1/getting-started (older v1)
+   * website.getVersionUrl('v2', '/docs/v1/getting-started')
+   * // → '/docs/getting-started' (latest has no prefix)
+   */
+  getVersionUrl(targetVersion, currentRoute) {
+    const scope = this.getVersionScope(currentRoute)
+    if (!scope) return null
+
+    const meta = this.versionedScopes[scope]
+    if (!meta) return null
+
+    // Find target version info
+    const targetVersionInfo = meta.versions.find(v => v.id === targetVersion)
+    if (!targetVersionInfo) return null
+
+    // Extract the path within the scope (after scope and any version prefix)
+    const afterScope = currentRoute.slice(scope.length) // e.g., '/getting-started' or '/v1/getting-started'
+
+    // Check if current route has a version prefix
+    let pathWithinVersion = afterScope
+    for (const version of meta.versions) {
+      const versionPrefix = `/${version.id}`
+      if (afterScope.startsWith(versionPrefix + '/') || afterScope === versionPrefix) {
+        // Remove version prefix
+        pathWithinVersion = afterScope.slice(versionPrefix.length)
+        break
+      }
+    }
+
+    // Build target URL
+    // Latest version has no prefix, others have /vN prefix
+    if (targetVersionInfo.latest) {
+      return scope + pathWithinVersion
+    } else {
+      return scope + '/' + targetVersion + pathWithinVersion
+    }
+  }
+
+  /**
+   * Get the latest version ID for a scope
+   *
+   * @param {string} scope - The scope route
+   * @returns {string|null} Latest version ID or null
+   */
+  getLatestVersion(scope) {
+    const meta = this.versionedScopes[scope]
+    return meta?.latestId || null
+  }
 }