@flamingo-stack/openframe-frontend-core 0.0.305 → 0.0.306-snapshot.20260622221324

package/dist/utils/seo-title.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Single source of truth for the `seo_title` length budget.
+ *
+ * The `seo_title` is rendered as the page `<title>` VERBATIM — no brand suffix is
+ * appended to it (the `| <Brand>` suffix is kept only on the default/actual-title
+ * fallback). So this is the full rendered-title budget; search engines truncate
+ * page titles around 60 chars.
+ *
+ * This number lives in exactly ONE place. Consumers:
+ *   - `SEOEditorPreview` — input `maxLength` + the too-long alert.
+ *   - the hub — imports it (via `@flamingo-stack/openframe-frontend-core/utils`)
+ *     for the AI generation prompt guidance and the DB CHECK value.
+ */
+export declare const SEO_TITLE_MAX_LENGTH = 60;
+//# sourceMappingURL=seo-title.d.ts.map

package/dist/utils/seo-title.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo-title.d.ts","sourceRoot":"","sources":["../../src/utils/seo-title.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.305",
+  "version": "0.0.306-snapshot.20260622221324",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/docs/use-document-tree.ts

@@ -22,6 +22,29 @@ function scrollToContent() {
   }
 }
 
+/**
+ * First displayable document inside a folder (depth-first): a direct non-Mermaid
+ * file, else the first doc found in a subfolder. Used so a folder WITHOUT a
+ * README shows its first child's content (mirroring how a README folder shows
+ * its README) instead of a blank panel or a redundant in-page listing — the
+ * sidebar tree is the directory browser. Returns null for a folder with no docs.
+ */
+function findFirstDocPath(folder: DocNode): string | null {
+  const children = folder.children ?? []
+  for (const child of children) {
+    if (child.type === 'file' && !child.path.toLowerCase().endsWith('.mmd')) {
+      return child.path
+    }
+  }
+  for (const child of children) {
+    if (child.type === 'folder') {
+      const nested = findFirstDocPath(child)
+      if (nested) return nested
+    }
+  }
+  return null
+}
+
 export interface UseDocumentTreeConfig {
   /** API endpoint for fetching the document tree structure */
   structureEndpoint: string
@@ -155,12 +178,24 @@ export function useDocumentTree(
       const node = findDocNodeByPath(selectedPath, structure)
 
       if (node && node.type === 'folder' && !node.hasReadme) {
-        return
-      }
-
-      pathToFetch = selectedPath
-      if (node && node.type === 'folder' && node.hasReadme) {
+        // No-README folder has no body of its own — show its FIRST child doc
+        // (mirrors a README folder showing its README). selectedPath stays the
+        // folder, so the sidebar keeps it highlighted/expanded; the sidebar is
+        // the directory browser, so we render NO separate in-page listing.
+        const firstDocPath = findFirstDocPath(node)
+        if (!firstDocPath) {
+          // Genuinely empty folder — clear to the empty state.
+          lastFetchedPath.current = null
+          setError(null)
+          setContent(null)
+          setIsLoadingContent(false)
+          return
+        }
+        pathToFetch = firstDocPath
+      } else if (node && node.type === 'folder' && node.hasReadme) {
         pathToFetch = `${selectedPath}/${folderIndexFile}`
+      } else {
+        pathToFetch = selectedPath
       }
     }
 
@@ -256,6 +291,25 @@ export function useDocumentTree(
             setContent(null)
             return
           }
+          // No-README FOLDER → stay silent: the content effect resolves it to
+          // the folder's first child, so the folder-path 404 from the direct-
+          // load speculative fetch is expected, not an error to flash.
+          const probe = findDocNodeByPath(
+            stripFolderIndexFromPath(path, folderIndexFile),
+            structure,
+          )
+          const probeIsNoReadmeFolder =
+            !!probe && probe.type === 'folder' && !probe.hasReadme
+          // Before the structure has loaded to classify the path (`structure`
+          // is [] in the speculative call's closure), only silence FOLDER-LIKE
+          // paths (no `.md`) — a genuinely missing `*.md` leaf must still error.
+          const preStructureFolderLike =
+            structure.length === 0 && !path.endsWith('.md')
+          if (probeIsNoReadmeFolder || preStructureFolderLike) {
+            setError(null)
+            setContent(null)
+            return
+          }
           setError(result.error || 'Documentation file not found')
           setContent(null)
           return
@@ -310,41 +364,32 @@ export function useDocumentTree(
   // narrower `NavigationNode` row shape) pass their own node back without the
   // cross-type `as` cast. Both DocNode and NavigationNode satisfy this.
   const selectNode = useCallback((node: Pick<DocNode, 'id' | 'path' | 'type' | 'hasReadme'>) => {
+    // Expansion only: clicking a folder toggles its own subtree; clicking a file
+    // reveals its ancestor chain.
     if (node.type === 'folder') {
       setExpandedNodes(prev => {
         if (prev.has(node.id)) {
           const ancestorIds = getDocAncestorNodeIds(node.path)
-          ancestorIds.pop()
+          ancestorIds.pop() // collapse self, keep ancestors open
           return new Set(ancestorIds)
-        } else {
-          return new Set(getDocAncestorNodeIds(node.path))
         }
+        return new Set(getDocAncestorNodeIds(node.path))
       })
-
-      if (node.hasReadme) {
-        lastFetchedPath.current = null
-        setSelectedPath(node.path)
-        window.history.pushState({}, '', `${normalizedBaseRoute}/${node.path}`)
-        setTimeout(() => {
-          scrollToContent()
-        }, 150)
-      } else {
-        setSelectedPath(node.path)
-      }
     } else {
       const lastSlash = node.path.lastIndexOf('/')
       if (lastSlash > 0) {
-        const parentPath = node.path.substring(0, lastSlash)
-        setExpandedNodes(new Set(getDocAncestorNodeIds(parentPath)))
+        setExpandedNodes(new Set(getDocAncestorNodeIds(node.path.substring(0, lastSlash))))
       }
-
-      lastFetchedPath.current = null
-      setSelectedPath(node.path)
-      window.history.pushState({}, '', `${normalizedBaseRoute}/${node.path}`)
-      setTimeout(() => {
-        scrollToContent()
-      }, 150)
     }
+
+    // Every node is a navigable destination — a file shows its body, a README
+    // folder its README, a no-README folder its first child doc (the content
+    // effect resolves which). So selection + URL + scroll are identical for all
+    // node types; no per-type special-casing.
+    lastFetchedPath.current = null
+    setSelectedPath(node.path)
+    window.history.pushState({}, '', `${normalizedBaseRoute}/${node.path}`)
+    setTimeout(scrollToContent, 150)
   }, [normalizedBaseRoute])
 
   const navigateToDoc = useCallback((path: string, options?: { expandFolder?: boolean; fromInternalLink?: boolean }) => {

package/src/components/features/seo-editor-preview.tsx

@@ -6,6 +6,9 @@ import { ConfidenceBadge } from '../features';
 import { Globe, ExternalLink, Upload, X, Loader2, Sparkles } from 'lucide-react';
 import { cn } from '../../utils';
 import Image from '../../embed-shims/next-image';
+// SSOT for the field cap (server-safe constant). The seo_title renders as the
+// page <title> verbatim (no brand suffix), so this is the full ~60-char budget.
+import { SEO_TITLE_MAX_LENGTH } from '../../utils/seo-title';
 
 export interface SEOEditorPreviewProps {
   // SEO fields - must be strings (not undefined)
@@ -68,6 +71,10 @@ export function SEOEditorPreview({
   const [isUploading, setIsUploading] = useState(false);
   const [fileInputRef, setFileInputRef] = useState<HTMLInputElement | null>(null);
 
+  // SEO title length state — alerts the editor when the title would render too long.
+  const seoTitleLength = (seoTitle || '').length;
+  const seoTitleTooLong = seoTitleLength > SEO_TITLE_MAX_LENGTH;
+
   // Use fallback values if OG fields are empty
   const displayTitle = seoTitle.trim() || title || 'Untitled';
   const displayDescription = seoDescription.trim() || summary || 'No description';
@@ -124,9 +131,26 @@ export function SEOEditorPreview({
             value={seoTitle || ''}
             onChange={(e) => onSeoTitleChange(e.target.value)}
             disabled={disabled}
+            maxLength={SEO_TITLE_MAX_LENGTH}
+            invalid={seoTitleTooLong}
             placeholder="Enter SEO meta title..."
             className="bg-ods-bg border-ods-border text-ods-text-primary"
           />
+          <div className="flex items-center justify-between gap-2">
+            <span className="text-[11px] text-ods-error font-['DM_Sans']">
+              {seoTitleTooLong
+                ? `Too long — search engines may truncate this title (keep it ≤ ${SEO_TITLE_MAX_LENGTH})`
+                : ''}
+            </span>
+            <span
+              className={cn(
+                "text-[11px] font-['DM_Sans'] tabular-nums shrink-0",
+                seoTitleTooLong ? 'text-ods-error font-semibold' : 'text-ods-text-secondary'
+              )}
+            >
+              {seoTitleLength}/{SEO_TITLE_MAX_LENGTH}
+            </span>
+          </div>
           {!seoTitle && title && (
             <p className="text-[11px] text-ods-accent font-['DM_Sans']">
               Auto-populated from title

package/src/utils/index.ts

@@ -26,6 +26,9 @@ export {
 } from './ods-color-utils'
 export { delay, generateRandomString, truncateString, deepClone, getSlackCommunityJoinUrl, serializeJsonLd } from './common'
 export { getBaseUrl } from '../utils/cn'
+// SEO title length budget — server-safe constant (SSOT). Consumed by the hub
+// (prompt guidance + DB check value) and by SEOEditorPreview (input maxLength).
+export { SEO_TITLE_MAX_LENGTH } from './seo-title'
 
 export * from './platform-config'
 export * from './os-platforms'

package/src/utils/seo-title.ts

@@ -0,0 +1,14 @@
+/**
+ * Single source of truth for the `seo_title` length budget.
+ *
+ * The `seo_title` is rendered as the page `<title>` VERBATIM — no brand suffix is
+ * appended to it (the `| <Brand>` suffix is kept only on the default/actual-title
+ * fallback). So this is the full rendered-title budget; search engines truncate
+ * page titles around 60 chars.
+ *
+ * This number lives in exactly ONE place. Consumers:
+ *   - `SEOEditorPreview` — input `maxLength` + the too-long alert.
+ *   - the hub — imports it (via `@flamingo-stack/openframe-frontend-core/utils`)
+ *     for the AI generation prompt guidance and the DB CHECK value.
+ */
+export const SEO_TITLE_MAX_LENGTH = 60;