lupine.press 1.0.0

package/README.md

@@ -0,0 +1,79 @@
+# lupine.press
+
+`lupine.press` is a lightweight, high-performance documentation site framework built on top of `lupine.web`. It provides a complete solution for rendering Markdown-based documentation websites with a responsive layout, sidebar navigation, and theming support.
+
+It is designed to work seamlessly with the `lupine` ecosystem, powering documentation sites like the official LupineJS documentation.
+
+## Features
+
+- **Responsive Layout**: Built-in `PressFrame` provides a standard documentation layout with a header, responsive sidebar, and content area.
+- **Markdown Rendering**: Optimized for rendering content generated from Markdown files, including syntax highlighting and standard typography.
+- **Sidebar Navigation**: Automatically generates a multi-level sidebar based on your configuration.
+- **Theming**: Built-in support for multiple themes (e.g., light/dark mode) via `lupine.components` theme system.
+- **Routing**: explicit integration with `PageRouter` for handling client-side navigation.
+- **多语言支持**：自动扫描多语言目录的 markdown 文件，多语言显示切换。
+
+## Usage Guide
+
+To use `lupine.press`, you typically set up a `lupine.web` application and configure it to use `PressPage` as the main route handler.
+
+### 1. Prerequisites
+
+Ensure you have `lupine.web` and `lupine.components` installed in your project.
+
+### 2. Basic Setup
+
+In your application entry point (e.g., `src/index.tsx`), you need to bind the necessary configurations and set up the router.
+
+```typescript
+import { bindRouter, PageRouter, bindTheme, bindLang, setDefaultPageTitle } from 'lupine.components';
+import { bindPressData, PressPage, pressThemes } from 'lupine.press';
+import { markdownConfig } from './markdown-config'; // Your generated markdown data
+
+// 1. Initialize core settings
+bindLang('en', {}); // Set default language
+bindTheme('light', pressThemes); // Bind themes (includes specific styles for press)
+setDefaultPageTitle('My Documentation');
+
+// 2. Bind documentation data
+// markdownConfig is a dictionary containing HTML content and metadata generated from markdown files.
+bindPressData(markdownConfig);
+
+// 3. Configure Router
+const pageRouter = new PageRouter();
+// Route all requests to PressPage, which handles looking up content in markdownConfig
+pageRouter.use('*', PressPage);
+
+// 4. Start the application
+bindRouter(pageRouter);
+```
+
+### 3. Data Structure (`markdownConfig`)
+
+The `bindPressData` function expects a configuration object where keys are route paths (e.g., `/guide/started`) and values contain the content and metadata.
+
+Typically, this data is generated at build time from your Markdown files.
+
+```typescript
+export const markdownConfig = {
+  '/en/guide/started': {
+    html: '<h1>Getting Started</h1><p>...</p>', // Pre-rendered HTML content
+    data: {
+      title: 'Getting Started',
+      sidebar: [
+        // Sidebar configuration for this page context
+        { type: 'group', text: 'Guide', level: 0 },
+        { type: 'link', text: 'Installation', link: '/en/guide/install', level: 1 },
+      ],
+    },
+    headings: [{ level: 2, text: 'Prerequisites', id: 'prerequisites' }],
+  },
+  // ... other pages
+};
+```
+
+## Architecture
+
+- **`PressFrame`**: The main layout component. It handles the specific CSS and structure for a documentation site, ensuring the sidebar and content area scroll independently.
+- **`PressPage`**: The "controller" component. It looks up the current URL in the bound `markdownConfig`, retrieves the corresponding HTML and metadata, and renders the `PressFrame` with the correct sidebar and content.
+- **`pressLoad`**: A navigation utility to handle link clicks within the documentation, ensuring smooth client-side transitions.

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "lupine.press",
+  "version": "1.0.0",
+  "description": "A modern documentation generator for lupine.js",
+  "main": "src/index.ts",
+  "license": "MIT",
+  "scripts": {
+    "note": "echo 'build is not needed as the typescript code is supposed to be referred directly from other projects'",
+    "npm-publish": "npm publish --access public"
+  },
+  "dependencies": {
+    "lupine.web": "^1.0.0",
+    "lupine.components": "^1.0.0",
+    "lupine.api": "^1.0.0",
+    "marked": "^15.0.0",
+    "gray-matter": "^4.0.3"
+  }
+}

package/src/components/index.ts

@@ -0,0 +1,7 @@
+export * from './lang-switcher';
+export * from './press-header';
+export * from './press-heading';
+export * from './press-home';
+export * from './press-layout';
+export * from '../services/press-load';
+export * from './press-sidemenu';

package/src/components/lang-switcher.tsx

@@ -0,0 +1,38 @@
+import { initializePage } from 'lupine.web';
+import { PopupMenu } from 'lupine.components';
+import langIcon from '../styles/lang.svg';
+import { Svg } from 'lupine.components';
+
+export const LangSwitcher = (props: { className?: string; currentLang: string; langs: any[] }) => {
+  const langs = props.langs || [];
+  const currentLabel = langs.find((l) => l.id === props.currentLang)?.text || 'Language';
+
+  const handleSelected = (text: string) => {
+    const lang = langs.find((l) => l.text === text);
+    if (lang && lang.id !== props.currentLang) {
+      let newPath = window.location.pathname;
+      const langIds = langs.map((l) => l.id).join('|');
+      const langRegex = new RegExp(`^/(${langIds})(\\/|$)`);
+
+      if (langRegex.test(newPath)) {
+        newPath = newPath.replace(langRegex, `/${lang.id}$2`);
+      } else {
+        newPath = `/${lang.id}${newPath === '/' ? '/' : newPath}`;
+      }
+      // window.location.href = newPath;
+      initializePage(newPath);
+    }
+  };
+
+  return (
+    <div class={['lang-switcher', props.className].join(' ')}>
+      <PopupMenu
+        list={langs.map((l) => l.text)}
+        defaultValue={currentLabel}
+        icon={<Svg>{langIcon}</Svg>}
+        handleSelected={handleSelected}
+        align='right'
+      />
+    </div>
+  );
+};

package/src/components/press-content.tsx

@@ -0,0 +1,146 @@
+import { CssProps, MediaQueryRange, MenuItemProps, PopupMenu, Svg, VNode } from 'lupine.components';
+import { pressLoad } from '../services/press-load';
+import { LayoutHome } from './press-home';
+import { PageHeading } from './press-heading';
+import menuIcon from '../styles/menu.svg';
+
+export const PressContent = (props: {
+  children: VNode<any>;
+  isHome: boolean;
+  sidebar: any[];
+  headings: any[];
+  data: any;
+}) => {
+  const css: CssProps = {
+    display: 'flex',
+    flex: 1,
+    maxWidth: '100vw',
+    margin: '0 auto',
+    width: '100%',
+    '.press-content': {
+      flex: 1,
+      padding: props.isHome ? '0' : '2rem 4rem',
+      width: '100%',
+      // maxWidth: isHome ? '100%' : '800px',
+      margin: props.isHome ? '0' : '0 auto',
+      minWidth: 0,
+    },
+    '.page-heading-container': {
+      width: '240px',
+      minWidth: '240px',
+      padding: '2rem 1rem',
+      position: 'sticky',
+      top: '64px',
+      maxHeight: 'calc(100vh - 64px)',
+      overflowY: 'auto',
+      alignSelf: 'flex-start', // Prevent stretching to full height
+      display: props.isHome || props.headings.length === 0 ? 'none' : 'block',
+    },
+    '.markdown-body': {
+      lineHeight: 1.6,
+    },
+    '.press-mobile-toc': {
+      display: 'none',
+      // border: '1px solid var(--press-border-color)',
+      borderRadius: '6px',
+      alignItems: 'center',
+      padding: '4px',
+      position: 'fixed',
+      top: '74px',
+      right: '7px',
+      zIndex: 90,
+      fontSize: '0.9rem',
+      cursor: 'pointer',
+      textTransform: 'uppercase',
+      backgroundColor: 'var(--primary-bg-color)',
+    },
+    '.press-mobile-sidebar': {
+      display: 'none',
+      borderRadius: '6px',
+      alignItems: 'center',
+      padding: '4px',
+      position: 'fixed',
+      top: '74px',
+      left: '7px',
+      zIndex: 90,
+      fontSize: '0.9rem',
+      cursor: 'pointer',
+      // can't put up level, otherwise it will override parent's same level selector
+      [MediaQueryRange.TabletBelow]: {
+        display: 'flex',
+      },
+    },
+    [MediaQueryRange.MobileBelow]: {
+      '.page-heading-container': {
+        display: 'none',
+      },
+      '.press-mobile-toc': { display: 'flex' },
+    },
+  };
+  return (
+    <main css={css}>
+      {!props.isHome && props.sidebar.length > 0 && (
+        <div class='press-mobile-sidebar'>
+          <PopupMenu
+            list={props.sidebar.map(
+              (item: any) =>
+                ({
+                  text: item.text,
+                  id: item.link || '',
+                  url: item.link || '',
+                  indent: item.level,
+                  visible: item.type ? true : false, // Validating it's processed item
+                  disabled: item.type === 'group',
+                  bold: item.type === 'group',
+                } as MenuItemProps)
+            )}
+            defaultValue='Menu'
+            tips=''
+            width='max-content'
+            maxHeight='400px'
+            align='left'
+            handleSelected={(text: string, item: any) => {
+              if (item && item.url) pressLoad(item.url);
+            }}
+            noUpdateLabel={true}
+            icon={<Svg>{menuIcon}</Svg>}
+          ></PopupMenu>
+        </div>
+      )}
+
+      <main class='press-content'>
+        {props.isHome ? <LayoutHome data={props.data} /> : <article class='markdown-body'>{props.children}</article>}
+      </main>
+      <aside class='page-heading-container'>
+        <PageHeading headings={props.headings} />
+      </aside>
+      {!props.isHome && props.headings.length > 0 && (
+        <div class='press-mobile-toc'>
+          <PopupMenu
+            list={props.headings.map(
+              (h) =>
+                ({
+                  text: h.text,
+                  id: h.id,
+                  indent: h.level - 2,
+                } as MenuItemProps)
+            )}
+            defaultValue='On this page'
+            tips=''
+            width='max-content'
+            maxHeight='300px'
+            align='right'
+            handleSelected={(text: string) => {
+              const cleanText = text.trim();
+              const heading = props.headings.find((h) => h.text === cleanText);
+              if (heading) {
+                document.getElementById(heading.id)?.scrollIntoView(true);
+              }
+            }}
+            noUpdateLabel={true}
+          ></PopupMenu>
+        </div>
+      )}
+    </main>
+  );
+};

package/src/components/press-header.tsx

@@ -0,0 +1,80 @@
+import { CssProps, Svg, ThemeSelector } from 'lupine.components';
+import { LangSwitcher } from './lang-switcher';
+import githubIcon from '../styles/github.svg';
+import themeIcon from '../styles/theme.svg';
+
+export type PageHeaderProps = {
+  title: string;
+  nav: any[];
+  langs: any[];
+  currentLang: string;
+  github?: {
+    url: string;
+    title: string;
+  };
+};
+export const PageHeader = (props: PageHeaderProps) => {
+  const css: CssProps = {
+    width: '100%',
+    display: 'flex',
+    alignItems: 'center',
+    padding: '0.75rem 2rem',
+    justifyContent: 'space-between',
+    '.press-navbar-left': {
+      display: 'flex',
+      alignItems: 'center',
+      '.title': {
+        fontWeight: 'bold',
+        fontSize: '1.2rem',
+        marginRight: '1rem',
+      },
+      '.nav': {
+        display: 'flex',
+        gap: '1rem',
+      },
+    },
+    '.press-navbar-right': {
+      display: 'flex',
+      alignItems: 'center',
+      gap: '1.25rem',
+      '.navbar-item': {
+        display: 'flex',
+        alignItems: 'center',
+        textDecoration: 'none',
+        transition: 'color 0.2s',
+        '&:hover': { color: 'var(--press-brand-color)' },
+      },
+    },
+  };
+  return (
+    <header css={css} class='press-navbar'>
+      <div class='press-navbar-left'>
+        <div class='title'>
+          <a href='/'>{props.title}</a>
+        </div>
+        <nav class='nav'>
+          {props.nav.map((item: any) => (
+            <a href={item.link}>{item.text}</a>
+          ))}
+        </nav>
+      </div>
+      <div class='press-navbar-right'>
+        {props.langs.length > 1 && (
+          <LangSwitcher className='navbar-item' currentLang={props.currentLang} langs={props.langs || []} />
+        )}
+        <ThemeSelector className='navbar-item' icon={<Svg>{themeIcon}</Svg>} noUpdateLabel={true} />
+        {props.github && props.github.url && (
+          <a
+            href={props.github.url}
+            target='_blank'
+            rel='noopener noreferrer'
+            class='navbar-item'
+            title={props.github.title}
+          >
+            <Svg>{githubIcon}</Svg>
+          </a>
+        )}
+      </div>
+    </header>
+  );
+};

package/src/components/press-heading.tsx

@@ -0,0 +1,46 @@
+import { CssProps } from 'lupine.components';
+
+export const PageHeading = (props: { headings: any[] }) => {
+  if (props.headings.length === 0) return null;
+
+  const css: CssProps = {
+    '&-title': {
+      fontWeight: 'bold',
+      fontSize: '0.8rem',
+      textTransform: 'uppercase',
+      letterSpacing: '0.05em',
+      color: 'var(--primary-color)',
+      marginBottom: '0.8rem',
+    },
+    '&-list': {
+      listStyle: 'none',
+      padding: 0,
+      margin: 0,
+      borderLeft: '1px solid var(--press-border-color)',
+    },
+    '&-item': {
+      padding: '0.2rem 0 0.2rem 1rem',
+      fontSize: '0.85rem',
+      '&.level-3': { paddingLeft: '2rem' },
+      a: {
+        display: 'block',
+        transition: 'color 0.2s',
+        whiteSpace: 'nowrap',
+        overflow: 'hidden',
+        textOverflow: 'ellipsis',
+      },
+    },
+  };
+  return (
+    <div css={css}>
+      <div class='&-title'>On this page</div>
+      <ul class='&-list'>
+        {props.headings.map((h) => (
+          <li class={`&-item level-${h.level}`}>
+            <a href={`#${h.id}`}>{h.text}</a>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+};

package/src/components/press-home.tsx

@@ -0,0 +1,109 @@
+import { CssProps } from 'lupine.components';
+
+export const LayoutHome = (props: { data: any }) => {
+  const { hero, features } = props.data || {};
+  const css: CssProps = {
+    '.&-hero': {
+      padding: '64px 32px',
+      textAlign: 'center',
+      display: 'flex',
+      flexDirection: 'column',
+      alignItems: 'center',
+    },
+    '.&-hero-name': {
+      fontSize: '56px',
+      lineHeight: '64px',
+      fontWeight: 'bold',
+      background: 'linear-gradient(135deg, var(--press-brand-color) 30%, #4facfe 100%)',
+      '-webkit-background-clip': 'text',
+      '-webkit-text-fill-color': 'transparent',
+    },
+    '.&-hero-text': {
+      fontSize: '56px',
+      lineHeight: '64px',
+      fontWeight: 'bold',
+      marginTop: '8px',
+    },
+    '.&-hero-tagline': {
+      fontSize: '24px',
+      lineHeight: '36px',
+      color: 'var(--secondary-color)',
+      marginTop: '24px',
+      maxWidth: '576px',
+    },
+    '.&-hero-actions': {
+      display: 'flex',
+      gap: '12px',
+      marginTop: '48px',
+    },
+    '.&-button': {
+      display: 'inline-block',
+      padding: '0 20px',
+      lineHeight: '38px',
+      borderRadius: '20px',
+      fontWeight: '600',
+      textDecoration: 'none',
+      fontSize: '14px',
+    },
+    '.&-button.brand': {
+      backgroundColor: 'var(--press-brand-color)',
+      color: '#fff',
+    },
+    '.&-button.alt': {
+      backgroundColor: 'var(--secondary-bg-color)',
+      color: 'var(--primary-color)',
+      border: '1px solid var(--press-border-color)',
+    },
+    '.&-features': {
+      display: 'grid',
+      gridTemplateColumns: 'repeat(auto-fit, minmax(256px, 1fr))',
+      gap: '24px',
+      padding: '48px 32px',
+      maxWidth: '1152px',
+      margin: '0 auto',
+    },
+    '.&-feature-card': {
+      backgroundColor: 'var(--secondary-bg-color)',
+      padding: '24px',
+      borderRadius: '12px',
+      border: '1px solid var(--press-border-color)',
+    },
+    '.&-feature-title': {
+      fontSize: '20px',
+      fontWeight: 'bold',
+      marginBottom: '8px',
+    },
+    '.&-feature-details': {
+      fontSize: '14px',
+      color: 'var(--secondary-color)',
+      lineHeight: '22px',
+    },
+  };
+
+  return (
+    <div css={css}>
+      <section class='&-hero'>
+        <h1 class='&-hero-name'>{hero.name}</h1>
+        <p class='&-hero-text'>{hero.text}</p>
+        <p class='&-hero-tagline'>{hero.tagline}</p>
+        <div class='&-hero-actions'>
+          {hero.actions?.map((action: any) => (
+            <a href={action.link} class={`&-button ${action.theme}`}>
+              {action.text}
+            </a>
+          ))}
+        </div>
+      </section>
+      {features && (
+        <section class='&-features'>
+          {features.map((feature: any) => (
+            <div class='&-feature-card'>
+              <h2 class='&-feature-title'>{feature.title}</h2>
+              <p class='&-feature-details'>{feature.details}</p>
+            </div>
+          ))}
+        </section>
+      )}
+    </div>
+  );
+};

package/src/components/press-layout.tsx

@@ -0,0 +1,46 @@
+import { getCurrentLang } from 'lupine.web';
+import { PressFrame } from '../frames/press-frame';
+import { PageHeader } from './press-header';
+import { PressSidemenu } from './press-sidemenu';
+import { PressContent } from './press-content';
+
+export const PressLayout = (props: {
+  children: any;
+  title: string;
+  nav: any[];
+  sidebar: any[];
+  lang: string;
+  langs?: any[];
+  data?: any;
+  headings?: any[];
+  sidemenuWidth?: string;
+  github?: { url: string; title: string };
+}) => {
+  const isHome = props.data?.layout === 'home';
+  const headings = props.headings || [];
+  const currentLang = props.lang || getCurrentLang().langName;
+
+  const sidebar = props.sidebar || [];
+  const content = (
+    <PressContent sidebar={sidebar} isHome={isHome} headings={headings} data={props.data}>
+      {props.children}
+    </PressContent>
+  );
+  return (
+    <PressFrame
+      header={
+        <PageHeader
+          title={props.title}
+          nav={props.nav}
+          langs={props.langs || []}
+          currentLang={currentLang}
+          github={props.github}
+        />
+      }
+      sidemenu={<PressSidemenu sidebar={sidebar} />}
+      content={content}
+      hideSidemenu={isHome}
+      sidemenuWidth={props.sidemenuWidth}
+    />
+  );
+};

package/src/components/press-sidemenu.tsx

@@ -0,0 +1,74 @@
+import { CssProps } from 'lupine.components';
+import { pressLoad } from '../services/press-load';
+
+export const PressSidemenu = (props: { sidebar: any[] }) => {
+  const css: CssProps = {
+    width: '100%',
+    padding: '0 8px 8px',
+    height: 'max-content',
+    // overflowY: 'auto',
+    '&-item': {
+      marginBottom: '0.3rem',
+      display: 'block',
+      color: 'var(--text-color)',
+      textDecoration: 'none',
+      '&:hover': {
+        color: 'var(--primary-color)',
+      },
+    },
+    '&-group-title': {
+      fontWeight: 'bold',
+      marginTop: '0.5rem',
+      marginBottom: '0.5rem',
+      fontSize: '15px',
+      // color: 'var(--secondary-color)',
+      '&.group-level-0': {
+        marginTop: '1.5rem',
+        fontSize: '19px',
+      },
+      '&.group-level-1': {
+        marginTop: '0.75rem',
+        fontSize: '17px',
+      },
+    },
+    '&-active': {
+      color: 'var(--primary-color)',
+      fontWeight: 'bold',
+    },
+  };
+
+  // Expecting props.sidebar to be already flattened by parent
+  const flatList = props.sidebar || [];
+  const basePadding = 1; // rem
+
+  return (
+    <aside css={css}>
+      {flatList.map((item, index) => {
+        const style = { paddingLeft: `${item.level * basePadding}rem` };
+
+        if (item.type === 'group') {
+          return (
+            <div class={'&-group-title' + (' group-level-' + item.level)} style={style} key={index}>
+              {item.text}
+            </div>
+          );
+        } else {
+          return (
+            <a
+              class='&-item'
+              style={style}
+              href='javascript:void(0)'
+              onClick={() => {
+                pressLoad(item.link);
+                return false;
+              }}
+              key={index}
+            >
+              {item.text}
+            </a>
+          );
+        }
+      })}
+    </aside>
+  );
+};

package/src/frames/index.ts

@@ -0,0 +1 @@
+export * from './press-frame';