cycraft / planetar Goto Github PK

prerequisite

• #12

goal

a new TableOfContentsList
should look and work just like the default vuepress one:

See example of the vue press one: https://mesqueeb.github.io/vuex-easy-firestore/setup.html

Requirements

• must accept a prop called toc with a certain type (you have to invent) that will generate the TOC
• for initial implementation allowing only 2 levels depth is good enough
• feel free to just implement something similar to what I did at Blitzar:
  https://github.com/cycraft/blitzar/blob/production/packages/docs/src/layouts/DocsLayout.vue#L23~L37
• feel free to use that same library I used there

steps

• this component is to be called TableOfContents.vue and is to be added as new component inside the directory at packages/doc-builder (alongside #12)
• for all other steps, follow a similar pattern as you've done for #12

Prerequisite

#19

Goal

• write a short component description for each component in a JSDoc above the export default section

• rename ApiComponentExample to ApiCardInteractive

• renameMarkdownSection and CodeBlockSection to something else:

So we have some components which end in ...Section because they are to be used as a documentation "section", which incorporate whatever ... stands for with an extra section of some text?

This makes sense.

However, MarkdownSection and CodeBlockSection are a bit different as they just allow the use of a filePath as opposed to Markdown and CodeBlock.
Things to think about:

is it really necessary to separate Markdown and CodeBlock with their counterparts that can accept a filePath?

I believe so because projects not relying on webpack that still want to use Markdown might have problems when the webpack related code is included. But we need to rename Section to something else.

reproduction steps:

1. click on a chapter to scroll to it
2. ⌘R to reload
3. the page will reload and stay at the top of the page

• you may need to create a new test page that uses DocPage.vue in planetar/packages/dev to reproduce the issue

desired fix

• fix to be implemented at: DocPage.vue
• have DocPage detect when all examples/sections are mounted. (I'm listening to some events to know about this already)
• then the browser URL hash needs to be obtained and scrolled towards the section.
• use Quasar scroll utils to scroll to the element

I want to write code snippets that are toggolable between JS and TS.

because, TS users wanna see implementation examples with Typings included
but, JS users don't want to see this

Instead of having separate TS documentation, each code snippet should be toggolable between the two.

The change is to be implemented in the CodeBlock component:
https://github.com/CyCraft/planetar/blob/production/packages/markdown/src/components/CodeBlock.vue

The syntax could be to accept an array of languages and content.

By default it will show: content[0] language[0], and then there is a toggle in the top right somewhere to switch to the second language and content.

currently the props look like this (need refactoring so they accept String | Array):

Goal:

• we need to check if Planetar is usable with Vue CLI projects that don't have Quasar (currently it might still cause issues)
• we need to find out WHAT the issues are IF there are any -- and fix them as well
• eventually we might add some link to this Vue-CLI project to show how it can be set up

Steps:

• Create a new folder called dev-vue-cli in packages in which you create a new empty project with Vue CLI.

• Make sure the package.json is set to "private": true like the packages/dev project. (this prevents lerna from trying to publish this to NPM)

• Copy 3 simple Vue components from the packages/atoms folder into this Vue CLI project inside a folder called "components"

• lerna add planetar --scope dev-vue-cli

• Look at the packages/dev folder to see how Planetar is set up, and do the same for Vue CLI.

  • try to do the same as packages/dev/src/pages/component-gallery/PageComponentGallery.vue
  • don't forget to do:

import Planetar from 'planetar'
Vue.use(Planetar)

allow for extra description underneath the example

Example of source file:

bottom markdown content is to be displayed underneath example card here:
https://github.com/cycraft/planetar/blob/production/packages/example-card/src/components/ExampleSection.vue#L9

Will require manual parsing of file contents, as the top "description" part is retrieved via vue-docgen.

• use importHelpers raw loader to parse the file
• then use regex? to retrieve the bottom JSDoc comment section

currently a default prism CSS is loaded with code-block

• think of a way to do themes, and keep footprint small
• prepare prism file for Lucy theme as per the issue below:

jul-sh/lucy-vscode-theme#12

ComponentPicker

• create a new ComponentPicker.vue component
• extract the logic of ComponentPickerGrid so the "grid" is only the UI that depends on props
• make ComponentPicker use ComponentPickerGrid based on a prop called "kind" set to kind: 'grid'

ComponentPickerList

the ComponentPickerList should be a way simpler solution than the grid that looks something like this (more on this down below):

• add a new ComponentPickerList.vue component
• make ComponentPicker use ComponentPickerList based on a prop called "kind" set to kind: 'list'
• A list should exist out of v-for of the sub component: ComponentPickerListItem.vue (also to be made)

ComponentPickerListItem

• should receive a single filePath: string prop
• it should look very simple like the example screenshot above
• it should have a hover color
• based on the filePath the list item should retrieve the vue-docgen object (like ApiCards do) and it should extract these fields from that object: (1) the component "name" field, (2) the component "description" field.
• use the name and description to render the list item

based on a list of colors, generate the colors page.

Define how to write the sass file for colors and make sure the following things are included & extractable in a json

• name
  (automatically show the .c-, .bg- classes)
  (automatically show the $c- variable name)
• value
• description
• subcolorOf
  (this makes sure the color is shown as a subcolor of another color, grouped together)
• examplesSchema
  (this is an array with the EasyForms schema to show some examples on the right)
  (can be inline or can be a path pointing towards a json or js file that should export the schema array as default export)

Ways of tackling this:

• TheRealSyler/sass-lsp-server#3
• or use raw-loader and write manual REGEX to get the job done lol

Need to properly support sass styling:

Prerequisite

#19

Goal

Currently a picker grid or list would render atoms / molecules based on this code:

const { atoms, molecules } = getComponentPaths(componentFilesList)

Instead, we want to auto-detect all folders inside a "componentFilesList" and render all components found inside any folder. Not just atoms and molecules.

In the future, if people want to only show atoms and molecules like the original implementation, they can just pass that into the "include" prop to the component-gallery:

<ComponentGallery :include="['atoms/', 'molecules/']" />

So we make a list with all folders; subfolders & components, and we somehow display it nested in both the "ComponentPickerGrid" and "ComponentPickerList"

• implement the above

• deprecate the formElementPrefix prop. If the dev wants something like this, he can just group his "form elements" into a sub-folder in atoms.

I need to show Vuetify example on blitzar
But Vuetify -- as I found out -- is terrrrrrrible as drop-in into any project because of the CSS leaking all over the place!!! literally wtf...

So my plan is to render an example card with the regular template, script, style code for the Vuetify example, but then have the actual example not be rendered based on that, but be rendered based on an iframe instead. Then I host the example somewhere and am able to prevent CSS leakage!

• create a "list" view as alternative for the "grid" view in figma
• create a design from scratch for a "grid" view in figma (you can look at sokketsu dev page for the crappy implementation I have now)
• maybe start with the "list" view before you try the "grid" view -- in fact let's first just do the "list" view :D

the idea is that in the future, planetar's component gallery is not fixated on subfolders "atoms" or "molecules" but instead shows ANYTHING inside the "components" folder

the list view can be similar to a collapsable files list

• This means that both the "grid" view and "list" view might show atoms & molecules as folders or sections, but they might show other folder names as well.
• Also, the concept of folders in folders should be supported.
  • this means that in list view, the atoms folder could be expanded to show nested folders which in turn can be expanded
  • in "grid" view I have no idea how to best create this concept, so you'll have to play around in Figma until it makes sense :P (let's finish the list view first)

inspiration

also look at

• macOS "finder" or the iOS "files" app for inspiration
• the Dropbox app
• the Google Drive app
• the VSCode "files" section on the left
• any "file" related app for inspiration

steps to reproduce:

1. click on a link in the example section eg. like on https://blitzar.cycraft.co

2. observe that it doesn't work! :O

reason:

• currently when a markdown link is written like so: [something](#some-chapter) it will push this on top of the main URL: blitzar.cycraft.co/#some-chapter

bad workaround:

• in the markdown URLs I can write [something](/docs/blitz-form#some-chapter) instead.
• this is less than ideal however, because it's ugly and prone to break when I change routing

desired fix:

• fix to be implemented at: DocPage.vue
• you may need to create a new test page that uses DocPage.vue in planetar/packages/dev to reproduce the issue and implement this fix more easily
• have DocPage detect when all examples/sections are mounted. (I'm listening to some events to know about this already)
• then scrape the DOM for all links in the markdown sections that start with #, and then attach an eventListener that does e.preventDefault() and e.stopPropagation()
• use Quasar scroll utils to scroll to the element
• the duration that it takes to have Quasar scroll to the element should be SCROLL_DURATION (do a global search for this in planetar)
• after clicking a link and after the scroll is complete the hashtag scrolled to, should be added to the URL in the browser:

   /**
     * @param {MouseEvent} event
     */
    setUrlHash(event) {
      const activeTocHash = event.srcElement.getAttribute('href')
      const activeTocId = activeTocHash.replace('#', '')
      this.willBecomeActiveTocId = activeTocId
      this.activeTocId = ''
      setTimeout(() => {
        location.hash = activeTocId
      }, SCROLL_DURATION)
    },

• this setUrlHash is also used by TOC.vue? so this logic should be in a planetar/packages/doc-builder/src/helpers/utils.ts file or something and imported into both TOC.vue and DocPage.vue

Currently H3 and down is automatically shown/hidden (see gif).

I want it to be a prop you can set to choose at which header depth you want auto show/hide

need <Markdown />; <MarkdownSection />; <CodeBlock /> components

initial steps

• npm run dep:install
• create a new package under packages/markdown
• copy all the boiler plate of packages/atoms but delete all components and add 3 new components: Markdown.vue; MarkdownSection.vue; CodeBlock.vue.
• make sure the index.js and package.json files are adjusted (we don't need a build step for now, the npm module can be exposed directly from the source files without compilation)
• the "name" in package.json should be @planetar/markdown
• add the package to the dev project so you can develop: lerna add @planetar/markdown --scope dev
• npm run dev
• make a dev page for in the dev project for each of the new components below (check other examples when you open the dev server)

Markdown component

I want to swap out this line with <Markdown />

• base implementation on the line mentioned above from ExampleSection.vue
• use <slot>{ content }</slot> so both the default slot and a prop called content can be used to render the markdown.
• Add a dev page with an example of the <Markdown /> component (npm run dev)

MarkdownSection component

MarkdownSection will just be a wrapper for <MarkDown /> but accept a filePath instead (just like ExampleSection).

• have a filePath as only prop
• filePath must point to a markdown file
• implement something like:

import { dynamicImport } from '@planetar/utils'
// and on created
dynamicImport(filePath, 'md', 'string')
  .then(markdownContent => doSomething(markdownContent))

• for this implementation we need to add 'md' as possibility to the dynamicImport function
• 'md' should only use the rawLoader and therefore the last param has to be 'string' or else an error is to be thrown
• Add a dev page with an example of the <MarkdownSection /> component (npm run dev)

CodeBlock component

I want to swap out this part with <CodeBlock />

• I think by now you can guess what this should do and how to implement it : )
• feel free to choose appropriate prop names
• Add a dev page with 3 examples of the <CodeBlock /> component - one for JS, one for HTML, one for CSS

finally

• expose all three components at packages/planetar

we can't use global margin-padding helper classes like
[m/p][d]-[size]

need to change with using the sass mixin equivalent

https://github.com/egoist/vue-compile

need to clarify how to style Planetar

Currently nested <template> tags will cause the template code block to be cut off short:

prerequisite

• #13

goal

need a DocPage component that can host multiple examples and an API Card at the bottom

eg.

it's a matter of creating a component out of this code:
https://github.com/cycraft/blitzar/blob/production/packages/docs/src/pages/DocsPage.vue
(you don't need to use the composition api)

problem with current implementation

One problem with the current implementation is that there's no way to have regular markdown chapters in between examples.

We see it's a problem with eg. "Events" In which I want to show 1 main example, then 2 other examples with H2 titles, instead of rendering the "Events 2" and "Events 3" H1 titles as well.

required implementation details

have the user pass two props:

• "pathToDocPageFolder"
• "chapterOrder"

The chapterOrder should be the file names (without extension) inside the "doc page files folder". It can be a combination of .vue and .md files. Whenever it's a .vue file, it's rendered with <ExampleSection />. Whenever it's an .md file, it's rendered with <MarkdownSection />. (see #14)

Now we have a mix of examples and just markdown sections, but then we need to know if the titles of each markdown / example are H1s or H2s.

The solution to that is to not render H1s based on the file names, like I'm doing now in the Blitzar docs. But force the dev to add # Some Title manually to each example/markdown section.

steps

• this component is to be called DocPage.vue and is to be create inside a new directory at packages/doc-builder
• copy paste a package.json from any other package (api-card, example-card, ...)
• update package name to be @planetar/doc-builder
• clear out all the package dependencies
• lerna add @planetar/example-card --scope @planetar/doc-page
• lerna add @planetar/markdown --scope @planetar/doc-page
• add the package to the dev project so you can develop: lerna add @planetar/doc-builder --scope dev
• npm run dev
• make a dev page for in the dev project for the new DocPage component (check other examples when you open the dev server)

other requirements

• The component needs to somehow create and emit a TOC after rendering (to be able to pass to #11)
• This TOC needs to be based on all the h1 & h2 titles
• write in a way it's easy later to expand to deeper levels

probably the easiest way for this TOC to implement is using javascript to "look" at the DOM rendered in the mounted hook. This method is good enough for now.

For the typography we need to show:

A list of all typography classes from top to bottom.
Include the CSS classes to use these.

example file

@import url("https://fonts.googleapis.com/css2?family=Open+Sans&family=Poppins:wght@400;500;600;700&display=swap")

body
  font-family: 'Poppins', sans-serif

.t-h1
  font-weight: bold
  font-size: 56px
  line-height: 64px
  letter-spacing: 0.01em

.t-h2
  font-weight: 600
  font-size: 40px
  line-height: 56px

.t-h3
  font-weight: bold
  font-size: 36px
  line-height: 40px
  letter-spacing: 0.01em

.t-h4
  font-weight: 600
  font-size: 32px
  line-height: 40px

.t-h5
  font-weight: 600
  font-size: 24px
  line-height: 30px
  letter-spacing: 0.01em

.t-h6
  font-weight: 600
  font-size: 20px
  line-height: 24px

.t-subtitle1
  font-weight: 600
  font-size: 16px
  line-height: 20px

.t-subtitle2
  font-weight: 500
  font-size: 14px
  line-height: 20px
  letter-spacing: 0.005em

.t-body1
  font-family: Open Sans
  font-weight: normal
  font-size: 16px
  line-height: 24px

.t-body2
  font-family: Open Sans
  font-weight: normal
  font-size: 14px
  line-height: 20px
  letter-spacing: 0.01em

.t-button
  font-weight: 600
  font-size: 14px
  line-height: 24px
  letter-spacing: 0.01em

.t-caption
  font-weight: normal
  font-size: 12px
  line-height: 16px
  letter-spacing: 0.02em

.text-caption t semibold
  font-weight: 600
  font-size: 12px
  line-height: 16px
  letter-spacing: 0.02em

.t-overline
  font-weight: 600
  font-size: 12px
  line-height: 16px
  letter-spacing: 0.08em
  text-transform: uppercase

.t-micro
  font-weight: normal
  font-size: 10px
  line-height: 14px
  letter-spacing: 0.02em

With the <Markdown /> component:

Question

• when adding a single line break in between text, does it add 0 or 1 <br> in the rendered html?
• when adding double line breaks, does it add 1 or 2 <br> in the rendered html?

IF:

• adding a single line break == 1 <br> in the rendered html
• adding double line breaks == 2 <br> in the rendered html

THEN: This ticket can be closed (but I believe it doesn't)

Goal

IF:

• adding a single line break == 0 <br> in the rendered html
• adding double line breaks == 1 <br> in the rendered html

THEN: I want to change it to

• adding a single line break == 1 <br> in the rendered html
• adding double line breaks == 2 <br> in the rendered html

use
element.scrollIntoView({ behavior: "smooth" })

https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView

write in component README (jsdoc above export default) that safari needs polyfill:
https://github.com/iamdustan/smoothscroll

and example of how to install it.