handoff-app 1.2.2-7 → 2.0.0-0

package/src/utils/menu-shell.ts

@@ -0,0 +1,241 @@
+import * as fs from 'fs';
+import matter from 'gray-matter';
+import { startCase } from 'lodash';
+import path from 'path';
+import type { NavMenuItem, NavSubSection, SectionLink } from '../nav';
+
+/**
+ * Build-time menu *shell* builder.
+ *
+ * The docs navigation is two things: a SHELL (which sections exist, their order/titles, and which
+ * submenu slots are filled at runtime from the registry) and the runtime ENTITY lists
+ * (components/patterns/token sets) that the resolver splices into those slots. The shell is
+ * markdown-driven and therefore static per build; the entities are mutable at runtime and the
+ * resolved tree is served by `/api/docs/nav.json`.
+ *
+ * On Vercel the registry function cannot read `config/docs` markdown at request time — those reads
+ * use absolute build-machine paths (`HANDOFF_MODULE_PATH/...`) that do not exist on the deploy host
+ * and that nft cannot trace. So the shell is frozen here at build time (where the markdown is
+ * present) into `generated/nav-shell.json`, which the API route imports statically (bundled, path
+ * independent). The resolver combines it with runtime-variable records before the client renders it.
+ *
+ * This module is intentionally dependency-light and PURE (fs + gray-matter, no DB, no React, no
+ * `@handoff` aliases) so the compiled build pipeline (`dist/`) can import it — `src/app` is excluded
+ * from `tsc` and is not importable from the builder.
+ *
+ * It emits the canonical section structure with empty entity lists and `dynamic` splice markers.
+ * `src/nav/resolver.ts` is the sole place that fills those markers in every runtime mode.
+ */
+
+/** Back-compatible shell-builder names reconciled to the canonical navigation contract. */
+export type MenuShellSubItem = NavMenuItem;
+export type MenuShellSubSection = NavSubSection;
+export type MenuShellSection = SectionLink;
+
+export interface BuildMenuShellOptions {
+  /** Absolute path to the package docs root (`<modulePath>/config/docs`). */
+  docRoot: string;
+  /** Absolute path to the working-project page overrides (`<workingPath>/pages`), optional. */
+  workingPagesDir?: string;
+  /** Resolved app base path (e.g. `"foundations"` → no leading/trailing slash), optional. */
+  basePath?: string;
+}
+
+/**
+ * Paths that have dedicated route files and are therefore excluded from auto-scanned submenus.
+ * Single source of truth — the docs app imports this (re-exported there as `knownPaths`).
+ */
+export const KNOWN_PATHS = [
+  'assets',
+  'assets/fonts',
+  'assets/icons',
+  'assets/logos',
+  'foundations',
+  'foundations/colors',
+  'foundations/icons',
+  'foundations/effects',
+  'foundations/logos',
+  'foundations/logo',
+  'foundations/typography',
+  'system',
+  'system/component',
+  'system/tokens',
+  'system/tokens/foundations',
+  'system/tokens/foundations/colors',
+  'system/tokens/foundations/effects',
+  'system/tokens/foundations/typography',
+  'system/tokens/components',
+  'system/pattern',
+];
+
+/** Normalize the base path to the resolver's `"prefix/"` form (or `""`). */
+const normalizeBasePath = (basePath?: string): string => {
+  if (!basePath) {
+    return '';
+  }
+  return basePath.replace(/^\/+|\/+$/g, '') + '/';
+};
+
+/**
+ * The static Tokens submenu (Foundations only). Component token sets are mode-resolved runtime
+ * records, so the shell bakes only the deterministic Foundations entries. The resolver appends the
+ * component token-set records when it fills the dynamic slot. `basePath` must already be
+ * `"prefix/"`-normalized.
+ */
+export const buildTokensFoundationsMenu = (basePath: string): MenuShellSubItem[] => [
+  {
+    title: 'Foundations',
+    path: `${basePath}system/tokens/foundations`,
+    menu: [
+      { title: 'Colors', path: `${basePath}system/tokens/foundations/colors` },
+      { title: 'Effects', path: `${basePath}system/tokens/foundations/effects` },
+      { title: 'Typography', path: `${basePath}system/tokens/foundations/typography` },
+    ],
+  },
+];
+
+/**
+ * Recursively build menu entries from .md files in a directory (auto-scan for sections that do not
+ * declare a `menu` in frontmatter). Shared with the app — single source of truth for the auto-scan.
+ */
+export const buildMenuFromDirectory = (dirPath: string, urlPrefix: string): MenuShellSubItem[] => {
+  if (!fs.existsSync(dirPath)) return [];
+  const entries = fs.readdirSync(dirPath);
+  const items: (MenuShellSubItem & { weight?: number })[] = [];
+
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry);
+    if (fs.lstatSync(fullPath).isDirectory()) {
+      const nestedItems = buildMenuFromDirectory(fullPath, `${urlPrefix}/${entry}`);
+      if (nestedItems.length > 0) {
+        items.push({ title: startCase(entry), path: `${urlPrefix}/${entry}`, menu: nestedItems });
+      }
+    } else if (entry.endsWith('.md') && entry !== 'index.md') {
+      const slug = entry.replace('.md', '');
+      const fullSlugPath = `${urlPrefix}/${slug}`.replace(/^\/+/, '');
+      if (KNOWN_PATHS.indexOf(fullSlugPath) >= 0) continue;
+
+      const contents = fs.readFileSync(fullPath, 'utf-8');
+      const { data: metadata } = matter(contents);
+      if (metadata.enabled === false) continue;
+
+      items.push({
+        title: metadata.menuTitle ?? metadata.title ?? startCase(slug),
+        path: `/${fullSlugPath}`,
+        weight: metadata.weight ?? 0,
+      });
+    }
+  }
+
+  return items.sort((a, b) => (a.weight ?? 0) - (b.weight ?? 0));
+};
+
+/**
+ * Build the full navigation shell from the docs markdown, with all registry entity slots
+ * (components/patterns/token sets) emitted empty and tagged `dynamic` for the resolver to fill.
+ *
+ * Returns the top-level `MenuShellSection[]` sorted by weight — the same shape the docs app's
+ * `SectionLink[]` uses, so it serializes directly into `generated/nav-shell.json`.
+ */
+export const buildMenuShell = (options: BuildMenuShellOptions): MenuShellSection[] => {
+  const { docRoot, workingPagesDir } = options;
+  const basePath = normalizeBasePath(options.basePath);
+
+  if (!fs.existsSync(docRoot)) {
+    return [];
+  }
+
+  const docFiles = fs.readdirSync(docRoot);
+  let pageFiles: string[] = [];
+  if (workingPagesDir && fs.existsSync(workingPagesDir)) {
+    pageFiles = fs.readdirSync(workingPagesDir);
+  }
+  // De-duplicate; working-project pages win over package docs (same as the app).
+  const list = Array.from(new Set([...docFiles, ...pageFiles]));
+
+  const sections: MenuShellSection[] = [];
+  for (const fileName of list) {
+    const fromPages = pageFiles.includes(fileName);
+    const search = fromPages ? path.resolve(workingPagesDir as string, fileName) : path.resolve(docRoot, fileName);
+
+    if (
+      fs.lstatSync(search).isDirectory() ||
+      search === path.resolve(docRoot, 'index.md') ||
+      (workingPagesDir && search === path.resolve(workingPagesDir, 'index.md')) ||
+      !fileName.endsWith('md')
+    ) {
+      continue;
+    }
+
+    const contents = fs.readFileSync(search, 'utf-8');
+    const { data: metadata } = matter(contents);
+    if (metadata.enabled === false) {
+      continue;
+    }
+
+    const filepath = `/${fileName.replace('.md', '')}`;
+    const subSections: MenuShellSubSection[] = [];
+
+    if (metadata.menu) {
+      for (const key of Object.keys(metadata.menu)) {
+        const sub = metadata.menu[key];
+        if (sub.components) {
+          // Omit `type` entirely when there is no filter (`undefined` is not JSON-serializable).
+          const dynamic =
+            typeof sub.components === 'string'
+              ? { kind: 'components' as const, type: sub.components }
+              : { kind: 'components' as const };
+          subSections.push({ title: sub.title, menu: [], dynamic });
+        } else if (sub.tokens) {
+          // Foundations are baked (deterministic); the resolver appends published component token
+          // sets into this slot when it builds the refreshed registry tree.
+          subSections.push({ title: 'Tokens', menu: buildTokensFoundationsMenu(basePath), dynamic: { kind: 'token-components' } });
+        } else if (sub.patterns) {
+          // Always keep the empty patterns slot in the shell for the resolver to fill on refresh.
+          subSections.push({ title: sub.title || 'Patterns', menu: [], dynamic: { kind: 'patterns' } });
+        } else if (sub.enabled !== false) {
+          subSections.push(sub as MenuShellSubSection);
+        }
+      }
+    } else {
+      // No frontmatter menu: auto-scan the matching directory (working pages win over docs).
+      const dirName = fileName.replace('.md', '');
+      const nestedFromDocs = buildMenuFromDirectory(path.resolve(docRoot, dirName), `/${dirName}`);
+      const nestedFromPages = workingPagesDir
+        ? buildMenuFromDirectory(path.resolve(workingPagesDir, dirName), `/${dirName}`)
+        : [];
+      const seenPaths = new Set<string>();
+      const children: MenuShellSubItem[] = [];
+      for (const item of [...nestedFromPages, ...nestedFromDocs]) {
+        if (item.path && !seenPaths.has(item.path)) {
+          seenPaths.add(item.path);
+          children.push(item);
+        }
+      }
+      // Wrap the scanned children under one labeled group (no `path`) so the side nav renders them as
+      // links — a flat subsection carrying a `path` but no `menu` renders nothing. This matches the
+      // record-backed nesting produced by the resolver so all modes remain structurally identical.
+      if (children.length > 0) {
+        subSections.push({ title: metadata.menuTitle ?? metadata.title, menu: children });
+      }
+    }
+
+    let external: string | boolean = false;
+    if (
+      typeof metadata.external === 'string' &&
+      (metadata.external.startsWith('http://') || metadata.external.startsWith('https://') || metadata.external.startsWith('/'))
+    ) {
+      external = metadata.external;
+    }
+
+    sections.push({
+      title: metadata.menuTitle ?? metadata.title,
+      external,
+      weight: metadata.weight ?? 0,
+      path: filepath,
+      subSections,
+    });
+  }
+
+  return sections.sort((a, b) => a.weight - b.weight);
+};

package/src/utils/stable-stringify.ts

@@ -0,0 +1,7 @@
+/** Serialize a value with object keys sorted at every nesting level. */
+export const stableStringify = (value: unknown): string =>
+  JSON.stringify(value, (_, nestedValue) =>
+    nestedValue && typeof nestedValue === 'object' && !Array.isArray(nestedValue)
+      ? Object.fromEntries(Object.entries(nestedValue).sort(([left], [right]) => left.localeCompare(right)))
+      : nestedValue
+  );

package/templates/default/package.json.tpl

@@ -6,7 +6,7 @@
   "scripts": {
     "start": "handoff-app start",
     "dev": "handoff-app dev",
-    "build": "handoff-app build:app",
+    "build": "handoff-app build",
     "fetch": "handoff-app fetch"
   },
   "dependencies": {},

package/handoff.config.js

@@ -1,90 +0,0 @@
-/** @type {import('handoff-app').Config} */
-const path = require('path');
-module.exports = {
-  // Set your Figma project ID here or in the environment variable HANDOFF_FIGMA_PROJECT_ID
-  figma_project_id: null,
-  // Set the output directory for the exported components
-  exportsOutputDirectory: 'exported',
-  // Set the output directory for the sites
-  sitesOutputDirectory: 'out',
-  // These settings control the behavior of the application
-  app: {
-    // Set the theme for the application
-    theme: 'default',
-    // Set the title for the application
-    title: 'Handoff Design System',
-    // Set the client for the application, used in the footer
-    client: 'Handoff Technologies',
-    // Set the Google Tag Manager ID to add GTM scripts
-    google_tag_manager: null,
-    // Set the attribution for the application
-    attribution: true, // Should we remove this?
-    // Set the type copy for the typeography page
-    type_copy: 'Almost before we knew it, we had left the ground.',
-    // Set the type sort for the typeography page
-    type_sort: [
-      'Heading 1',
-      'Heading 2',
-      'Heading 3',
-      'Heading 4',
-      'Heading 5',
-      'Heading 6',
-      'Paragraph',
-      'Subheading',
-      'Blockquote',
-      'Input Labels',
-      'Link',
-    ],
-    // Set the color sort for the color page
-    color_sort: ['primary', 'secondary', 'extra', 'system'],
-    // Set the component sort for the component page
-    component_sort: ['primary', 'secondary', 'transparent'],
-    // Set the base path for the application
-    base_path: '',
-    // Set the breakpoints for the application
-    breakpoints: {
-      sm: { size: 576, name: 'Small' },
-      md: { size: 768, name: 'Medium' },
-      lg: { size: 992, name: 'Large' },
-      xl: { size: 1200, name: 'Extra Large' },
-    },
-    // Set the ports for the application
-    ports: { app: 3000, websocket: 3001 },
-  },
-  // These are the entry points used to compile the target application
-  entries: {
-    scss: './sass/main.scss',
-    js: './js/main.js',
-    bundle: './js/main.js',
-    //components: ['./test_components'],
-    //patterns: ['./test_patterns'],
-  },
-  // These are the asset zip file download links
-  assets_zip_links: {
-    icons: null,
-    logos: null,
-  },
-  // Hooks allow you to override the default behavior of the application
-  hooks: {
-    // Alter the vite css build config
-    cssBuildConfig: (config) => {
-      return config;
-    },
-    // Validate each component before it is exported
-    validateComponent: (component) => {
-      return {};
-    },
-    // Alter the vite client build config
-    clientBuildConfig: (config) => {
-      return config;
-    },
-    // Alter the vite html build config
-    htmlBuildConfig: (config) => {
-      return config;
-    },
-    // Alter the vite js build config
-    jsBuildConfig: (config) => {
-      return config;
-    },
-  },
-};

package/src/app/components/ComponentSearch.tsx

@@ -1,93 +0,0 @@
-import { ComponentListObject } from '@handoff/transformers/preview/types';
-import { Laptop, Search } from 'lucide-react';
-import Link from 'next/link';
-import React from 'react';
-
-/**
- * Get the Component List
- * @returns Promise<ComponentListObject[]>
- */
-export const getComponentList = async (): Promise<ComponentListObject[]> => {
-  // Try to load the component from the public json
-  let data = await fetch(`${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/components.json`).then((res) => res.json());
-  return data as ComponentListObject[];
-};
-
-const ComponentSearch = ({ }) => {
-  const [search, setSearch] = React.useState('');
-  const [loading, setLoading] = React.useState(true);
-  const [list, setList] = React.useState<ComponentListObject[]>([]);
-
-  const filterList = React.useCallback<React.ChangeEventHandler<HTMLInputElement>>((event) => {
-    setSearch(event.currentTarget.value.toLowerCase().replace(/[\W_]+/g, ' '));
-    // filter list by search
-    const filteredList = list.filter((component) => {
-      return component.title.toLowerCase().includes(search) || component.description.toLowerCase().includes(search);
-    });
-    setList(filteredList);
-  }, []);
-
-  React.useEffect(() => {
-    getComponentList().then((data) => {
-      setList(data);
-      setLoading(false);
-    });
-  }, []);
-
-  if (loading) {
-    return <p>Loading...</p>;
-  }
-
-  if (!list) {
-    return <p>{JSON.stringify(list)}No icons found</p>;
-  }
-
-  return (
-    <>
-      <div className="c-form-element c-form-element--fullwidth c-form-element--big">
-        <div className="c-form-element__field">
-          <div className="c-form-element__icon">
-            <Search />
-          </div>
-          <input type="text" className="c-form-element__text" placeholder="Search icons..." onChange={filterList} />
-        </div>
-      </div>
-      <p>
-        <strong>{list.length}</strong> found
-      </p>
-      <div className="o-row">
-        <div className="o-col-12@md">
-          <div className="o-stack-1@md o-stack-1@lg">
-            {list.length > 0 ? (
-              list.map((component) => <DisplayComponent key={component.id} component={component} />)
-            ) : (
-              <div className="c-search-results">
-                <Laptop />
-                <h4>No icons found.</h4>
-              </div>
-            )}
-          </div>
-        </div>
-      </div>
-    </>
-  );
-};
-
-export const DisplayComponent: React.FC<{ component: ComponentListObject }> = ({ component }) => {
-  return (
-    <div>
-      <Link href={`/components/single/${component.id}`}>
-        <div className="c-card c-card--component-preview">
-          <div className="o-row">
-            <div className="o-col-12@md">
-              <h4>{component.title}</h4>
-              <p>{component.description}</p>
-            </div>
-          </div>
-        </div>
-      </Link>
-    </div>
-  );
-};
-
-export default ComponentSearch;