From 7e55a5c7c12b6f147cc2dc76755ee99859fe0aee Mon Sep 17 00:00:00 2001 From: heyjul3s Date: Fri, 26 Mar 2021 11:39:30 +1100 Subject: [PATCH] readme updates for generator, artifak, fluidsizing, container, text-input and typography --- README.md | 3 + packages/artifak/README.md | 4 +- packages/component-generator/README.md | 182 +++++++++++++++---------- packages/container/README.md | 30 +++- packages/fluidsizing/README.md | 2 +- packages/text-input/README.md | 67 ++++++++- packages/typography/README.md | 58 ++++++-- 7 files changed, 255 insertions(+), 91 deletions(-) diff --git a/README.md b/README.md index f6d5fab..dfa87c4 100644 --- a/README.md +++ b/README.md @@ -23,15 +23,18 @@ npm install artifak Packages can also be installed independently. Simply do `yarn add ` or `npm install ` to add them to your list of dependencies. Below is a list of available packages. +- @artifak/**container** - @artifak/**grid** - @artifak/**typography** - @artifak/**flex** +- @artifak/**text-input** - @artifak/**component-generator** - @artifak/**imagery** - @artifak/**media** - @artifak/**fluidsizing** - @artifak/**usematchmedia** - @artifak/**usewindowsize** +- @artifak/**usedebouncedfn** - @artifak/**hextorgb** - @artifak/**hextorgba** - @artifak/**pxtoem** diff --git a/packages/artifak/README.md b/packages/artifak/README.md index c41396d..5e4923e 100644 --- a/packages/artifak/README.md +++ b/packages/artifak/README.md @@ -20,16 +20,18 @@ npm install artifak Packages can also be installed independently. Simply do `yarn add ` or `npm install ` to add them to your list of dependencies. Below is a list of available packages. -- @artifak/**block** +- @artifak/**container** - @artifak/**grid** - @artifak/**typography** - @artifak/**flex** +- @artifak/**text-input** - @artifak/**component-generator** - @artifak/**imagery** - @artifak/**media** - @artifak/**fluidsizing** - @artifak/**usematchmedia** - @artifak/**usewindowsize** +- @artifak/**usedebouncedfn** - @artifak/**hextorgb** - @artifak/**hextorgba** - @artifak/**pxtoem** diff --git a/packages/component-generator/README.md b/packages/component-generator/README.md index 493fbd4..f567f09 100644 --- a/packages/component-generator/README.md +++ b/packages/component-generator/README.md @@ -1,7 +1,7 @@ # `@artifak/component-generator` Component Generator library to generate similar components based off of styles and or attributes you provide. You can also view the docs -at [Artifak Typography](https://www.artifak.dev/?content=Generator). +at [Artifak Generator](https://www.artifak.dev/?content=Generator). ## Installation @@ -19,82 +19,122 @@ npm install @artifak/component-generator ## Usage -### createStyledComponent - -To generate your components, simply define a config object consisting of styles/attributes with the key as your component name. Note that you **must** define the `as` property in order to have it render as the HTML tag that you desire. In the example below, we've defined a component called `H1` to render as an `h1` HTML tag. We've also defined the fontSize in an array that matches the media query widths. +### createComponents -| Arguments | Type | -| --------- | ------ | -| config | object | +This generates components based on the config provided. Below a usage example with full configuration applied. ```ts -import { createStyledComponent } from '@artifak/component-generator'; -import { system } from 'styled-system'; - -const styles = { - fontSize: [16, 36, 96], - margin: 0, - as: 'h1' -}; - -const variants = { - primary: { - color: 'red' - }, - secondary: { - color: 'blue' - } -}; - -const styleProps = [ - system({ - textTransform: true - }) -]; - -const element = 'h1'; - -const H1 = createStyledComponent({ - styles, - variants, - styleProps, - element -}); -``` +import { position, PositionProps } from 'styled-system'; + import { createComponents } from 'artifak'; + import { theme } from './theme'; -### createBaseComponents + // # EXAMPLE 1 - USING A CONFIGURATION OBJECT AS BASE + // Note that this is just an example, please use the + // "button" HTML element whenever possible. In the + // examples, we will see full usage of the + // createComponents function. -createBaseComponents will require a base Styled Component to generate your desired components. This is used to conveniently generate similar components. For creating the base component, you can use createStyledComponent. - -| Arguments | Type | -| --------- | ------ | -| styles | object | - -```ts -import { - createStyledComponent, - createBaseComponents -} from '@artifak/component-generator'; - -const baseComponentConfig = { - styles: { - display: 'block', - margin: '0 auto' - } -}; - -const BaseComponent = createStyledComponent(); - -const typeSettings = { - H1: { + const base = { styles: { - fontSize: [16, 17, 19, 21], - lineHeight: 1.5, - marginTop: 0, - as: 'h1' + display: 'block', + padding: ['1em', '1.5em 1em'], + width: '100%', + fontSize: ['1rem', '1.2rem'] + }, + styleProps: [position], + attrs: { role: 'button' }, + element: 'div' + }; + + // Define your component styles + const config = { + TextButton: { + background: transparent, + border: 'none', + '&:hover': { + color: theme.colors.primary + }, + attrs: { name: 'text-button' }, + as: 'span' + }, + + FilledButton: { + margin: '0 auto', + padding: ['1.2em 1em', '1.5em 1.2em'], + background: theme.colors.primary + '&:hover': { + background: theme.colors.secondary + }, + attrs: { name: 'filled-button' } + }, + + OutlinedButton: { + background: transparent, + border: 1px solid black, + padding: 0, + '&:hover': { + borderColor: theme.colors.primary + }, + attrs: { name: 'outlined-button' } } - } -}; + }; + + // Invoke and destructure for usage. Since a configuration object + // is provided, you will also get the base as a component. + // You can rename it as use as a base for something else if desired. + export const { + Base: ButtonBase, + FilledButton, + OutlinedButton, + TextButton + } = createComponents(BaseComponent, config); + + + // # EXAMPLE 2 - USING A COMPONENT AS BASE + // You can also pass in a component to use as base. + // For example, let us create a BasicButton component. + + const BasicButton = styled('div')( + { + display: 'block', + padding: ['1em', '1.5em 1em'], + width: '100%', + fontSize: ['1rem', '1.2rem'] + } + ); + + // Invoke and call like Example 1. Here we will reuse the + // config constant we previously defined in Example 1. + // Note that passing a component as base will not yield + // a Base component in the results. + export const { + FilledButton, + OutlinedButton, + TextButton + } = createComponents(BasicButton, config); +``` + +### createStyledComponent -const { H1 } = createBaseComponents(typeSettings); +Creates a single styled component based on the configuration that you provide. + +```ts +import { HTMLAttributes } from 'react'; +import { position, PositionProps } from 'styled-system'; +import { theme } from './theme'; + +type CardProps = { + isHidden: boolean; +} & PositionProps; + +const StyledArticle = createStyledComponent< + CardProps, + typeof theme, + HTMLAttributes +>({ + styles: { position: 'relative' }, + attrs: { title: 'Hello World' }, + styledProps: [position], + element: 'article' +}); ``` diff --git a/packages/container/README.md b/packages/container/README.md index 7cdd752..3af1b69 100644 --- a/packages/container/README.md +++ b/packages/container/README.md @@ -1,11 +1,33 @@ # `@artifak/container` -> TODO: description +A basic container component. By default has full 100% width and margin 0 auto. All you need to do is specify your max widths. ## Usage -``` -const container = require('@artifak/container'); +Apart from widths, the component also accepts the following style properties: + +- background +- border +- color +- display +- layout +- position +- shadow +- space +- typography + +Below is a usage example. + +```ts +import { Container } from 'artifak'; -// TODO: DEMONSTRATE API +export function Example() { + return ( + + <> +

Hello World

+ + + ); +} ``` diff --git a/packages/fluidsizing/README.md b/packages/fluidsizing/README.md index ba051e6..3a1dfbe 100644 --- a/packages/fluidsizing/README.md +++ b/packages/fluidsizing/README.md @@ -1,6 +1,6 @@ # `@artifak/fluidsizing` -A utility function that computes a fluid sizing value based on the min and max values provided. +A utility function that computes a fluid sizing value based on the min and max values provided, eliminating the need for specifying width based media queries. Alternatively, docs can be found at [Artifak Fluid Sizing](https://www.artifak.dev/?content=Typography). ## Installation diff --git a/packages/text-input/README.md b/packages/text-input/README.md index 91ccf55..11d73ca 100644 --- a/packages/text-input/README.md +++ b/packages/text-input/README.md @@ -1,11 +1,70 @@ # `@artifak/text-input` -> TODO: description +A text based input element generator. -## Usage +## Installation + +### Yarn +```sh +yarn add @artifak/text-input ``` -const textInput = require('@artifak/text-input'); -// TODO: DEMONSTRATE API +### NPM + +```sh +npm install @artifak/text-input +``` + +## Usage + +```ts +import { createTextInputs } from '@artifak/text-input'; + +const inputs = { + base: { + styles: { + width: '100%', + border: '1px solid black', + padding: ['1em'] + } + }, + + components: { + InputSearch: { + maxWidth: '300px', + attrs: { type: 'search' } + }, + + InputUrl: { + display: 'block', + attrs: { type: 'url' } + } + } +}; + +type BasicUsageProps = { + disabled?: boolean; + placeholder?: string; + onBlur?: () => void; +}; + +const { Base: InputText, InputSearch, InputUrl } = createTextInputs< + typeof inputs.components, + BasicUsageProps +>(inputs.base, inputs.components); + +export function BasicUsage() { + const onBlur = (text: string) => () => { + console.log('Blur', text); + }; + + return ( + <> + + + + + ); +} ``` diff --git a/packages/typography/README.md b/packages/typography/README.md index a5465a8..5391544 100644 --- a/packages/typography/README.md +++ b/packages/typography/README.md @@ -21,24 +21,62 @@ npm install @artifak/typography ### createTypography -To generate your typography components, simply define a styles object with the key as your component name. Note that you **must** define the `as` property in order to have it render as the HTML tag that you desire. In the example below, we've defined a component called `H1` to render as an `h1` HTML tag. We've also defined the fontSize in an array that matches the media query widths. - -| Arguments | Type | -| --------- | ------ | -| styles | object | +Generates your typography components. ```ts -import { createTypography } from '@artifak/typography'; +import { createTypographyComponents, fontWeight } from 'artifak'; +import { theme } from '../theme'; + +const base = { + styles: { + color: theme.colors.text, + fontFamily: theme.fontFamily.arial + } +}; -const typeStyles = { +const components = { H1: { - fontSize: [16, 36, 96], - margin: 0, + fontSize: [48, 96], + margin: '0 0 0.25em', + lineHeight: 1.15, as: 'h1' + }, + + H2: { + fontSize: [37, 39, 41, 43], + lineHeight: 1.45, + as: 'h2' + }, + + H3: { + fontSize: [27, 28, 30, 32], + lineHeight: 1.45, + as: 'h3' + }, + + H4: { + fontSize: [18, 20, 22, 24], + lineHeight: 1.45, + as: 'h4' + }, + + H5: { + fontSize: [16, 17, 19, 21], + lineHeight: 1.45, + as: 'h5' + }, + + H6: { + fontSize: [16, 17, 19, 21], + lineHeight: 1.45, + as: 'h6' } }; -const { H1 } = createTypography(typeStyles); +export const { H1, H2, H3, H4, H5, H6 } = createTypography< + typeof components, + typeof theme +>(base, components); ``` Other than helping you generate new typography components, it also contains other utility functions as well to help you in styling.