cycraft / planetar Goto Github PK
View Code? Open in Web Editor NEWA Vue framework for creating a design system styleguide with interactive component explorer 🪐
License: MIT License
A Vue framework for creating a design system styleguide with interactive component explorer 🪐
License: MIT License
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.
Goal:
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.
packages/dev/src/pages/component-gallery/PageComponentGallery.vue
import Planetar from 'planetar'
Vue.use(Planetar)
need <Markdown />
; <MarkdownSection />
; <CodeBlock />
components
npm run dep:install
packages/markdown
packages/atoms
but delete all components and add 3 new components: Markdown.vue
; MarkdownSection.vue
; CodeBlock.vue
.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)package.json
should be @planetar/markdown
dev
project so you can develop: lerna add @planetar/markdown --scope dev
npm run dev
I want to swap out this line with <Markdown />
ExampleSection.vue
<slot>{ content }</slot>
so both the default slot and a prop called content
can be used to render the markdown.<Markdown />
component (npm run dev
)MarkdownSection will just be a wrapper for <MarkDown />
but accept a filePath
instead (just like ExampleSection
).
filePath
as only propfilePath
must point to a markdown fileimport { dynamicImport } from '@planetar/utils'
// and on created
dynamicImport(filePath, 'md', 'string')
.then(markdownContent => doSomething(markdownContent))
'string'
or else an error is to be thrown<MarkdownSection />
component (npm run dev
)I want to swap out this part with <CodeBlock />
<CodeBlock />
component - one for JS, one for HTML, one for CSSpackages/planetar
allow for extra description underneath the example
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.
we can't use global margin-padding helper classes like
[m/p][d]-[size]
need to change with using the sass mixin equivalent
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):
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
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
andCodeBlock
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.
steps to reproduce:
reason:
[something](#some-chapter)
it will push this on top of the main URL: blitzar.cycraft.co/#some-chapter
bad workaround:
[something](/docs/blitz-form#some-chapter)
instead.desired fix:
DocPage.vue
DocPage.vue
in planetar/packages/dev
to reproduce the issue and implement this fix more easily#
, and then attach an eventListener that does e.preventDefault()
and e.stopPropagation()
SCROLL_DURATION
(do a global search for this in planetar) /**
* @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)
},
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.vueCurrently 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.
need to clarify how to style Planetar
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!
currently a default prism CSS is loaded with code-block
blockquote
position: relative
margin-left: 0
+py($md)
+px($xl)
&:before,&:after
position: absolute
top: 0
&:after
content: '“'
left: 0.3em
font-size: 2em
line-height: 1.4em
&:before
content: ''
left: 0
width: 0.4em
height: 100%
background: currentColor
opacity: 0.1
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
.c-
, .bg-
classes)$c-
variable name)value
description
subcolorOf
examplesSchema
Ways of tackling this:
raw-loader
and write manual REGEX to get the job done lolreproduction steps:
DocPage.vue
in planetar/packages/dev
to reproduce the issuedesired fix
DocPage.vue
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
toc
with a certain type (you have to invent) that will generate the TOCComponentPicker.vue
componentComponentPickerGrid
so the "grid" is only the UI that depends on propsComponentPicker
use ComponentPickerGrid
based on a prop called "kind" set to kind: 'grid'
the ComponentPickerList
should be a way simpler solution than the grid that looks something like this (more on this down below):
ComponentPickerList.vue
componentComponentPicker
use ComponentPickerList
based on a prop called "kind" set to kind: 'list'
v-for
of the sub component: ComponentPickerListItem.vue
(also to be made)filePath: string
propfilePath
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.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)
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.
have the user pass two props:
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.
DocPage.vue
and is to be create inside a new directory at packages/doc-builder
api-card
, example-card
, ...)@planetar/doc-builder
lerna add @planetar/example-card --scope @planetar/doc-page
lerna add @planetar/markdown --scope @planetar/doc-page
dev
project so you can develop: lerna add @planetar/doc-builder --scope dev
npm run dev
DocPage
component (check other examples when you open the dev server)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.
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
also look at
With the <Markdown />
component:
<br>
in the rendered html?<br>
in the rendered html?IF:
<br>
in the rendered html<br>
in the rendered htmlTHEN: This ticket can be closed (but I believe it doesn't)
IF:
<br>
in the rendered html<br>
in the rendered htmlTHEN: I want to change it to
<br>
in the rendered html<br>
in the rendered htmlA declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.