@startupjs-ui/docs 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## [0.1.3](https://github.com/startupjs/startupjs-ui/compare/v0.1.2...v0.1.3) (2025-12-29)
+
+**Note:** Version bump only for package @startupjs-ui/docs
+
+
+
+
+
+## [0.1.2](https://github.com/startupjs/startupjs-ui/compare/v0.1.1...v0.1.2) (2025-12-29)
+
+
+### Features
+
+* add mdx and docs packages. Refactor docs to get rid of any @startupjs/ui usage and use startupjs-ui instead ([703c926](https://github.com/startupjs/startupjs-ui/commit/703c92636efb0421ffd11783f692fc892b74018f))

package/README.md

@@ -0,0 +1,99 @@
+# startupjs docs
+> MDX Documentation generator
+
+## TODO:
+
+- currently only the Sandbox is usable, still need to update the docs app fully to use the new Expo project and new 'startupjs-ui' components in it.
+
+## Prerequisites
+
+You must be using `@startupjs/app` for routing.
+
+You can create a new application with the routing system using the `routing` template: `npx startupjs init myapp -t routing`
+
+## Installation
+
+```sh
+yarn add @startupjs/docs
+```
+
+## Requirements
+
+```
+react: 16.9 - 17
+react-native: >= 0.61.4 < 0.64.0
+startupjs: >= 0.33.0
+```
+
+## Usage
+
+1. Create the `docs/` folder in your project root.
+
+2. Create `docs/index.js` file with the following content:
+  ```js
+  import docs from '@startupjs-ui/docs'
+  export default docs({
+    typography: {
+      type: 'mdx',
+      // different titles for mdx documentation in English and Russian
+      title: {
+        en: 'Typography',
+        ru: 'Типографика'
+      },
+      // different components to display for English and Russian documentation
+      component: {
+        en: require('../components/typography/Typography.en.mdx').default,
+        ru: require('../components/typography/Typography.ru.mdx').default
+      }
+    },
+    cssGuide: {
+      type: 'mdx',
+      // the same title for both English and Russian mdx documentation
+      title: 'Typography',
+      // the same component to display for English and Russian documentation
+      component: require('../components/typography/Typography.en.mdx').default
+    },
+    // docs in collapse
+    // items have the same api as mdx docs
+    components: {
+      type: 'collapse',
+      title: {
+        en: 'Components',
+        ru: 'Компоненты'
+      },
+      items: {
+        Button: {
+          type: 'mdx',
+          title: {
+            en: 'Button',
+            ru: 'Кнопка'
+          }
+          component: {
+            en: require('../components/Button/Button.en.mdx').default,
+            ru: require('../components/Button/Button.ru.mdx').default
+          }
+        },
+        Card: {
+          type: 'mdx',
+          title: 'Card',
+          component: require('../components/Card/Card.en.mdx').default
+        }
+      }
+    }
+  })
+  ```
+
+3. Add client-side `docs` app to your `Root/App.js` file:
+
+    ```js
+    import docs from '../docs'
+    // ...
+    <App
+      apps={{ main, docs }}
+      // ...
+    />
+    ```
+
+## License
+
+MIT

package/client/app/Layout/Sidebar/Content/Docs/index.js

@@ -0,0 +1,118 @@
+import React, { useCallback, useEffect, useMemo } from 'react'
+import { pug, observer, useModel, useLocal } from 'startupjs'
+import { pathFor } from 'startupjs/app'
+import { useMedia, Menu, Collapse } from '@startupjs/ui'
+import { faAngleRight } from '@fortawesome/free-solid-svg-icons/faAngleRight'
+import { getTitle, useLang } from '../../../../../clientHelpers'
+import { useDocsContext } from '../../../../../../docsContext'
+import './index.styl'
+
+const MenuItem = observer(function MenuItemComponent ({
+  active,
+  doc,
+  docName,
+  docPath,
+  nestingLevel,
+  superPath
+}) {
+  const [lang] = useLang()
+  const { desktop } = useMedia()
+  const $mainSidebar = useModel('_session.Sidebar.mainSidebar')
+  const $openedCollapses = useModel('_session.SidebarCollapses')
+
+  const menuItemStyle = useMemo(() => ({ paddingLeft: nestingLevel * 24 }), [nestingLevel])
+  const title = useMemo(() => getTitle(doc, lang), [doc, lang])
+  const rootPath = useMemo(() => pathFor('docs:doc', { lang, path: docPath }), [lang, docPath])
+
+  if (doc.type === 'collapse') {
+    return pug`
+      Collapse(
+        variant='pure'
+        $open=$openedCollapses.at(docPath)
+      )
+        Collapse.Header.header(
+          iconPosition='right'
+          icon=faAngleRight
+          iconStyleName='collapse-icon'
+        )
+          Menu.Item(
+            style=menuItemStyle
+            active=active
+            to=doc.component ? rootPath : null
+            bold
+            icon=doc.icon
+          )= title
+        Collapse.Content
+          Docs(
+            docs=doc.items
+            superPath=docPath
+            nestingLevel=nestingLevel + 1
+          )
+    `
+  }
+
+  return pug`
+    Menu.Item.item(
+      style=menuItemStyle
+      active=active
+      to=rootPath
+      onPress=desktop ? undefined : () => $mainSidebar.set(false)
+    )= title
+  `
+})
+
+const Docs = observer(function DocsComponent ({ docs, superPath, nestingLevel = 1 }) {
+  const [path] = useLocal('$render.params.path')
+  const $openedCollapses = useModel('_session.SidebarCollapses')
+
+  // HACK: open parent collapse on initial render
+  useEffect(() => {
+    if (superPath && path.startsWith(superPath)) {
+      $openedCollapses.setDiff(superPath, true)
+    }
+  }, [])
+
+  const getDocPath = useCallback(
+    docName => {
+      return superPath ? superPath + '/' + docName : docName
+    },
+    [superPath]
+  )
+
+  const getActive = useCallback(
+    docName => {
+      return getDocPath(docName) === path
+    },
+    [path]
+  )
+
+  return pug`
+    Menu
+      each docName in Object.keys(docs)
+        MenuItem(
+          key=docName
+          active=getActive(docName)
+          doc=docs[docName]
+          docName=docName
+          docPath=getDocPath(docName)
+          nestingLevel=nestingLevel
+          superPath=superPath
+        )
+  `
+})
+
+export default observer(function DocsRoot () {
+  const docs = useDocsContext()
+  const [path] = useLocal('$render.params.path')
+
+  // NOTE
+  // since layout renders before page loads
+  // and $render is created when page loads
+  // we need to wait for the 'path' to appear
+  // in the params
+  if (!path) return null
+
+  return pug`
+    Docs(docs=docs)
+  `
+})

package/client/app/Layout/Sidebar/Content/Docs/index.styl

@@ -0,0 +1,12 @@
+.header
+  padding-right 3u
+  padding-top 0.5u
+  padding-bottom 0.5u
+
+.collapse
+  &-icon
+    color var(--color-text-description)
+
+.link
+  text-decoration none
+  bleed()

package/client/app/Layout/Sidebar/Content/Options/index.js

@@ -0,0 +1,52 @@
+import React from 'react'
+import { pug, observer, useValue, $ } from 'startupjs'
+import { Br, Input, Button, Modal } from '@startupjs/ui'
+import { faSlidersH } from '@fortawesome/free-solid-svg-icons/faSlidersH'
+import {
+  useShowGrid,
+  useShowSizes
+  // useValidateWidth
+} from '../../../../../clientHelpers'
+import './index.styl'
+
+export default observer(function Options ({
+  style
+}) {
+  const [, $open] = useValue(false)
+  const [, $showGrid] = useShowGrid()
+  // TODO: figure out why getting showSizes here leads to a bug of being non-reactive
+  //       initially. While $showSizes.get() works fine for some reason.
+  const [, $showSizes] = useShowSizes()
+  // const [, $validateWidth] = useValidateWidth()
+  const $theme = $.session.theme
+  const theme = $theme.get() || 'light'
+
+  function toggleTheme () {
+    if (theme === 'light') {
+      $theme.set('dark')
+    } else {
+      $theme.set('light')
+    }
+  }
+
+  return pug`
+    Button(
+      style=style
+      icon=faSlidersH
+      color='text-description'
+      variant='text'
+      onPress=() => $open.set(true)
+    )
+    Modal(
+      title='Settings'
+      $visible=$open
+    )
+      Input.input(type='checkbox' label='Dark theme' value=theme === 'dark' onChange=toggleTheme)
+      if $showSizes.get()
+        //- TODO: Maybe bring width check back in future
+        // Input.input(type='checkbox' label='Validate width' $value=$validateWidth)
+        Input.input(type='checkbox' label='Show grid' $value=$showGrid)
+      Input.input(type='checkbox' label='Show sizes' $value=$showSizes)
+      Br
+  `
+})

package/client/app/Layout/Sidebar/Content/Options/index.styl

@@ -0,0 +1,11 @@
+.header
+  padding 1u 1u 1u 2u
+  background-color var(--color-bg-main)
+
+.content
+  padding-top 2u
+  padding-bottom 2u
+  padding-left 1u
+
+.input
+  margin-top 1u

package/client/app/Layout/Sidebar/Content/index.js

@@ -0,0 +1,38 @@
+import React from 'react'
+import { ScrollView, Image } from 'react-native'
+import { pug, observer } from 'startupjs'
+import { Div, Select } from '@startupjs/ui'
+import { BASE_URL } from '@env'
+import { useLang } from '../../../../clientHelpers'
+import Options from './Options'
+import Docs from './Docs'
+import './index.styl'
+
+const LANGUAGES = [
+  { value: 'en', label: 'English' },
+  { value: 'ru', label: 'Русский' }
+]
+
+export default observer(function Content ({
+  style
+}) {
+  const [lang, setLang] = useLang()
+  // TODO: Change logo image to base64 and pass it through context
+  const baseUrl = BASE_URL
+
+  return pug`
+    Div.root
+      ScrollView
+        Image.logo(testID='logo' source={ uri: baseUrl + '/img/docs.png' })
+        Docs
+      Div.footer(row)
+        Select.lang(
+          testID='languagesSelect'
+          options=LANGUAGES
+          value=lang
+          onChange=setLang
+          showEmptyValue=false
+        )
+        Options.options
+  `
+})

package/client/app/Layout/Sidebar/Content/index.styl

@@ -0,0 +1,35 @@
+.root
+  background-color var(--color-bg-main)
+  flex 1
+
+.main
+  flex 1
+
+.subMenuItem
+  padding-left 4u
+
+.logo
+  width 7.5u
+  height 7.5u
+  align-self center
+  margin-top 4u
+  margin-bottom 4u
+
+.hr
+  border-bottom-color var(--color-border-main)
+
+.footer
+  padding-top 1u
+  padding-bottom 1u
+  padding-left 2u
+  padding-right 0.5u
+  background-color var(--color-bg-main-subtle)
+
+.lang
+  // TODO: flex-grow 1 for some reason gets removed. Research.
+  flex-grow 2
+  flex-shrink 1
+
+.options
+  margin-left 0.5u
+  flex-shrink 0

package/client/app/Layout/Sidebar/index.js

@@ -0,0 +1,24 @@
+import React from 'react'
+import { pug, observer, useModel } from 'startupjs'
+import { SmartSidebar } from '@startupjs/ui'
+import Content from './Content'
+
+export const SIDEBAR_PATH = '_session.Sidebar.mainSidebar'
+
+function renderContent () {
+  return pug`Content`
+}
+
+export default observer(function Sidebar ({ children }) {
+  const $open = useModel(SIDEBAR_PATH)
+
+  return pug`
+    SmartSidebar(
+      $open=$open
+      width=280
+      renderContent=renderContent
+      defaultOpen
+    )
+      = children
+  `
+})

package/client/app/Layout/index.js

@@ -0,0 +1,97 @@
+import React, { useState } from 'react'
+import { pug, emit, observer, useModel } from 'startupjs'
+import { pathFor, useLocation } from 'startupjs/app'
+import { AutoSuggest, Button, Div, Layout, Menu, Span } from '@startupjs/ui'
+import { ScrollableProvider } from '@startupjs/scrollable-anchors'
+import { faBars } from '@fortawesome/free-solid-svg-icons/faBars'
+import { faSearch } from '@fortawesome/free-solid-svg-icons/faSearch'
+import Sidebar, { SIDEBAR_PATH } from './Sidebar'
+import { useDocsContext } from '../../../docsContext'
+import { useLang, getTitle } from '../../clientHelpers'
+import './index.styl'
+
+function getItems (item, lang, subpath) {
+  const docKey = item[0]
+  const docPath = subpath ? `${subpath}/${docKey}` : docKey
+  const rootPath = pathFor('docs:doc', { lang, path: docPath })
+  if (item[1].items) {
+    return Object.entries(item[1].items).reduce((acc, item) => {
+      return [...acc, ...getItems(item, lang, docPath)]
+    }, [])
+  } else {
+    return [{
+      value: rootPath,
+      label: getTitle(item[1], lang)
+    }]
+  }
+}
+
+function renderItem (item, path) {
+  const active = item.value === path
+  return pug`
+    Menu.Item(
+      key=item.value
+    )
+      Span(
+        styleName={active}
+        numberOfLines=1
+      )= item.label
+  `
+}
+
+const Search = observer(function Search () {
+  const [value, setValue] = useState({})
+  const { pathname } = useLocation()
+  const docs = useDocsContext()
+  const [lang] = useLang()
+
+  const options = Object.entries(docs).reduce((acc, item) => {
+    return [...acc, ...getItems(item, lang)]
+  }, [])
+
+  function onChange (value) {
+    if (!value) return
+    setValue({})
+    // TODO: replaced from Menu.Item 'to' property
+    emit('url', value.value)
+  }
+
+  return pug`
+    AutoSuggest.search(
+      testID='searchInput'
+      value=value
+      options=options
+      placeholder='Search...'
+      inputIcon=faSearch
+      renderItem=item => renderItem(item, pathname)
+      onChange=onChange
+    )
+  `
+})
+
+const Topbar = observer(function Topbar () {
+  const $open = useModel(SIDEBAR_PATH)
+
+  function toggleSidebar () {
+    $open.set(!$open.get())
+  }
+
+  return pug`
+    Div.topbar(row)
+      Button(testID='button' variant='text' icon=faBars onPress=toggleSidebar color='text-description')
+      Div.searchWrapper
+        Search
+  `
+})
+
+export default observer(function StyleguideLayout ({ children }) {
+  // Note: Topbar height is compensated in PDoc
+  //       to achieve a semi-transparent effect
+  return pug`
+    Layout.layout(testID="Layout")
+      Sidebar
+        Topbar
+        ScrollableProvider
+          = children
+  `
+})

package/client/app/Layout/index.styl

@@ -0,0 +1,31 @@
+@require '../constants.styl'
+
+.layout
+  background-color var(--color-bg-main-strong)
+
+.topbar
+  align-items center
+  justify-content space-between
+  border-bottom-width 1px
+  border-bottom-color var(--color-border-main-strong-alt)
+  height $TOPBAR_HEIGHT
+  padding 0 1u
+
+.searchWrapper
+  width 32u
+  border-left-width 1px
+  border-left-color var(--color-border-main)
+  padding-left 2u
+
+  +tablet()
+    width 42u
+
+.search
+  max-height 20u
+  &:part(input)
+    border none
+  &:part(icon)
+    color var(--color-text-description)
+
+.active
+  color var(--color-text-primary)

package/client/app/constants.styl

@@ -0,0 +1 @@
+$TOPBAR_HEIGHT = 6u

package/client/app/index.js

@@ -0,0 +1,5 @@
+import * as pages from './pages'
+import getRoutes from './routes'
+
+export { default as Layout } from './Layout'
+export const routes = getRoutes(pages)

package/client/app/pages/PDoc/index.js

@@ -0,0 +1,46 @@
+import React from 'react'
+import { pug, observer, useLocal } from 'startupjs'
+import { Span, Br, Div } from '@startupjs/ui'
+import { useDocsContext } from '../../../../docsContext'
+import { useLang } from '../../../clientHelpers'
+import './index.styl'
+
+export default observer(function PDoc ({
+  style
+}) {
+  const docs = useDocsContext()
+  const [docPath] = useLocal('$render.params.path')
+  const segments = docPath.split('/')
+  const [lang] = useLang()
+  const Component = segments.reduce((docs, segment, index) => {
+    const doc = docs[segment]
+    if (!doc) return PageNotFound
+    // when page with 'collapse' type has a component to render
+    // to display it we have to figure out if it is the last segment or not
+    if (doc.type === 'collapse' && segments.length - 1 !== index) {
+      return doc.items
+    }
+    const Component = getComponent(doc, lang)
+    return Component || PageNotFound
+  }, docs)
+
+  return pug`
+    Div.content
+      Br
+      Component
+      Br(lines=4)
+  `
+})
+
+function PageNotFound () {
+  return pug`
+    Span.message Page not found
+  `
+}
+
+function getComponent (item, lang) {
+  if (!item) return
+  if (!item.component) return
+  if (item.component[lang]) return item.component[lang]
+  return item.component
+}

package/client/app/pages/PDoc/index.styl

@@ -0,0 +1,21 @@
+$gutter-l = 6u
+$gutter-xl = 10u
+
+.root
+  flex 1
+
+.content
+  padding-left $UI.gutters.m
+  padding-right $UI.gutters.m
+  max-width $UI.media.tablet + $UI.gutters.m * 2
+  +tablet()
+    max-width $UI.media.tablet + $gutter-l * 2
+    padding-left $gutter-l
+    padding-right $gutter-l
+  +wide()
+    max-width $UI.media.tablet + $gutter-xl * 2
+    padding-left $gutter-xl
+    padding-right $gutter-xl
+
+.message
+  font(h2)

package/client/app/pages/PHome/index.js

@@ -0,0 +1,33 @@
+import { useEffect } from 'react'
+import { observer, emit } from 'startupjs'
+import { useDocsContext } from '../../../../docsContext'
+
+export default observer(function PHome () {
+  const docs = useDocsContext()
+
+  function getDocPath (docs) {
+    let path = '/'
+    const docName = Object.keys(docs)[0]
+    const doc = docs[docName]
+    switch (doc.type) {
+      case 'mdx':
+        path += docName
+        break
+      case 'collapse':
+        path += docName
+        if (!doc.component) path += getDocPath(doc.items)
+        break
+    }
+    return path
+  }
+
+  useEffect(() => {
+    emit(
+      'url',
+      '/docs' + getDocPath(docs),
+      { replace: true }
+    )
+  }, [])
+
+  return null
+})

package/client/app/pages/index.js

@@ -0,0 +1,2 @@
+export { default as PHome } from './PHome'
+export { default as PDoc } from './PDoc'

package/client/app/routes.js

@@ -0,0 +1,15 @@
+export default function (components = {}) {
+  return [
+    {
+      path: '/docs',
+      exact: true,
+      component: components.PHome
+    },
+    {
+      path: '/docs/:path+',
+      exact: true,
+      component: components.PDoc,
+      name: 'docs:doc'
+    }
+  ]
+}

package/client/clientHelpers/getTitle.js

@@ -0,0 +1,11 @@
+import { DEFAULT_LANGUAGE } from '../const'
+
+export default function getTitle (item, lang) {
+  const title = item.title
+    ? typeof item.title === 'string'
+      ? item.title
+      : item.title[lang] || item.title[DEFAULT_LANGUAGE]
+    : null
+  if (!title) throw Error('No title specified')
+  return title
+}