From eb777b9de76e5a2f5758bcbc597955333f73afa5 Mon Sep 17 00:00:00 2001 From: Gustavo Lizze Date: Sun, 10 May 2026 11:42:03 -0300 Subject: [PATCH] chore: improve docs --- docs/docs/examples.mdx | 13 +- docs/docs/getting-started/animations.mdx | 7 +- docs/docs/getting-started/installation.mdx | 3 + docs/docs/getting-started/overview.mdx | 271 ++++++++-------- docs/docs/getting-started/systems.mdx | 297 +++++++++++++----- docs/docs/getting-started/theming.mdx | 4 +- .../getting-started/withPieceAsContainer.mdx | 10 +- docs/package.json | 1 + docs/pnpm-lock.yaml | 29 ++ docs/src/css/custom.css | 5 + docs/src/theme/ReactLiveScope/index.tsx | 12 +- package.json | 5 + src/index.ts | 1 + src/systems/harmony/container.ts | 12 + src/systems/harmony/index.ts | 10 +- vite.config.ts | 1 + 16 files changed, 440 insertions(+), 241 deletions(-) create mode 100644 src/systems/harmony/container.ts diff --git a/docs/docs/examples.mdx b/docs/docs/examples.mdx index d402df4..8a1c855 100644 --- a/docs/docs/examples.mdx +++ b/docs/docs/examples.mdx @@ -5,16 +5,15 @@ sidebar_label: 'Showcases' # Showcases +import IframeResizer from '@iframe-resizer/react'; + ## Color Picker: - [Website](https://lizzelabs.github.io/css-colors/) - [Github](https://github.com/lizzelabs/css-colors) - + style={{ width: '500px', height: '500px' }} + inPageLinks +> diff --git a/docs/docs/getting-started/animations.mdx b/docs/docs/getting-started/animations.mdx index f7fc02e..97fd9da 100644 --- a/docs/docs/getting-started/animations.mdx +++ b/docs/docs/getting-started/animations.mdx @@ -11,7 +11,7 @@ We basically have two ways of working with css animations Example: -```tsx showLineNumbers +```tsx const Main = () => { return ( Property: `withStyle` -As I said before, everything is a piece remember ? So you can do at your -`withStyle` property: +So you can do at your `withStyle` property: -```tsx showLineNumbers +```tsx const Main = () => { return ( diff --git a/docs/docs/getting-started/installation.mdx b/docs/docs/getting-started/installation.mdx index c17d544..f834ee6 100644 --- a/docs/docs/getting-started/installation.mdx +++ b/docs/docs/getting-started/installation.mdx @@ -50,3 +50,6 @@ export const Main = () => { return ; }; ``` + +Now, +[**_Let's talk about Css Systems, How you can implement yours_**](./systems.mdx) diff --git a/docs/docs/getting-started/overview.mdx b/docs/docs/getting-started/overview.mdx index 6a44041..81c0c55 100644 --- a/docs/docs/getting-started/overview.mdx +++ b/docs/docs/getting-started/overview.mdx @@ -6,100 +6,167 @@ slug: / # πŸ“– Introduction to React Harmony -Nowadays we have a lot of style libs, and many times we dont need to everything -in each one to build our interfaces, it costs to our users download every css -class unused, so i think in an easy and elegant way to style all of components -and how to keep everything easy to mantain and fast to develop new components. +Nowadays We have a lot of style libs and Many times we dont need to everything +at our packages. It costs to our users, Mobile data usually is poor at any place +of the World. -## Main Idea +If You try to mixture many sort of style libs You'll get a truly hell into your +codebase. (I got you, no worry sometimes times matter πŸ˜‚) -Everything you should know about it is: all you need is a piece, I mean +Why not use something that able us to stylish our components so easily or even +setting patterns to style components improving our velocity to delivery. -```tsx showLineNumbers live -function Main(props) { +I mean with **`@lizzelabs/react-harmony`** you can: + +- Set patterns of what you have to style ex: + +```tsx showLineNumbers live noInline +const TitlePattern = { + order: 0, + applyOn: (props: any) => props.kind === 'title', + style: { + fontSize: '1rem', + fontWeight: 'bold', + }, +}; + +const SubtitlePattern = { + order: 0, + applyOn: (props: any) => props.kind === 'subtitle', + style: { + fontSize: '0.859rem', + fontWeight: '500', + }, +}; + +function Main() { return ( - + + as='h2' + kind='title' + > + Title + - Hello world! + Subtitle - - + ); } + +render(
); ``` -with it now you're able to set patterns to fill your styles, default properties -through a component called **`PieceProvider`** +- Even properties: ```tsx showLineNumbers live noInline -interface MyCustomTheme { - primaryColor: string; - textColor: string; +const ButtonPattern = { + order: 0, + applyOn: (props: any) => props.kind === 'button', + default: { + aria: { + role: 'button', + 'aria-label': 'action', + }, + }, +}; + +function Main() { + return ( + + + I am accessible. + +
+
+ + I am not. + + + ); } -interface TitleProps { - children?: string; +render(
); +``` + +- Set css-styles directly into **`JSX`**: + +```tsx showLineNumbers live +function Main() { + return ( + + ); +} +``` + +- Work with your own **`theme`** between your components: + +```tsx live showLineNumbers noInline +interface MyCustomTheme { + primary: string; + secondary: string; + text: string; + fontSize: string; } const Theme = { - primaryColor: '#FFF', - textColor: '#000', + primary: 'red', + secondary: 'blue', + text: '#FFF', + fontSize: '16px', } satisfies MyCustomTheme; -const Title = (props: TitleProps) => { - return ( - - ); -}; +const ContainerPattern = { + order: 0, + applyOn: (props: any) => props.kind === 'container', + styles: (theme: MyCustomTheme) => ({ + display: 'flex', + alignItems: 'center', + justifyContent: 'center', + }), +} satisfies ProviderPattern; + +const LabelPattern = { + order: 0, + applyOn: (props: any) => props.kind === 'label', + styles: (theme: MyCustomTheme) => ({ + color: theme.text, + fontSize: '0.85rem', + }), +} satisfies ProviderPattern; const Main = () => { return ( props.kind === 'title', - styles: (theme: MyCustomTheme) => ({ - background: theme.primaryColor, - color: theme.textColor, - }), - }, - ]} + patterns={[ContainerPattern, LabelPattern]} > - Now all of title are hidden from assistive technology + theme.fontSize} + withStyle={(theme: MyCustomTheme) => ({ + border: `1px solid ${theme.secondary}`, + })} + > + Hello word + ); }; @@ -107,71 +174,7 @@ const Main = () => { render(
); ``` -## Why do it - -I make easy to stylish your components with the most powerfull way to do it with -css in js: - -- Allow us to keep the power and core of our business rules for UI into one - language, javascript. - -so you can do inside your component: - -```ts -import { Piece } from '@lizzelabs/react-harmony'; - - - -// Or - - - ({ - background: theme.primaryColor, - transition: 'all 0.3s ease-in-out', - '&:hover': { - background: theme.hover, - }, - '@media screen (max-width: 500px)': { - background: theme.secondaryColor - }, - '@container card (max-width: 600px)': { - textOverflow: 'ellipsis' - }, - '@keyframes fade': { - from: { - opacity: 0; - } - to: { - opacity: 1; - } - } - }} > - Hello world! - - - -``` - -- You're able to set patterns for sort of components and their styles or default - properties. -- You keep your code easy to maintain. -- Keeping eveything as js you get the control about everything (you set your - rules in css more easy). +So while your codebase gets more clear you delivery more faster I mean you don't +need to transition between `css` and `js` It just one language πŸ€“. -**To keep easy to start you can import the default system flex + grid:** - -```js -import { HARMONY_SYSTEM, PieceProvider } from '@lizzelabs/react-harmony'; - -export const Main = () => { - return ( - - - - ); -}; -``` +[**_Now let's get start and see how It's easy to install_**](./installation.mdx) diff --git a/docs/docs/getting-started/systems.mdx b/docs/docs/getting-started/systems.mdx index a97a3eb..8d774cb 100644 --- a/docs/docs/getting-started/systems.mdx +++ b/docs/docs/getting-started/systems.mdx @@ -5,48 +5,40 @@ sidebar_label: 'Css Systems' # ♾️ Harmony System -Here how It works we have flex for all of sort of pieces and I want you to think -like this: +At the next lines I'll explain how the default system works and How you can +create or extend your one of your own: -- Flex as small parts of your screen (everything). -- Grid as large parts of your screen (where you want to align many flex pieces). +**`HARMONY_SYSTEM:`** -and I just make it easy to work: +First of all, I would like you to think as: -```js -import { Piece } from '@lizzelabs/react-harmomny'; +- **Flex:** **_``_** -export const Main = () => { - return ( - - - I am at first column and at first row. - - - I am at second column and at second row. - - - ); -}; -``` +_Small parts of your screen, everything you want to organize into a container +whatever the kind of them._ + +- **Grid:** **_``_** -All pieces has this css: +_Containers or your big parts of your screen where you want to organize your +small parts (flex)_ -```js +So everything that you need is a `piece` at other hand everything that you need +to organize our pieces is a `container` -export const PIECE: ProviderPattern = { +#### Basic Grid: + +```tsx showLineNumbers live noInline +const ContainerPattern = { + order: 0, + applyOn: (props: PieceProperties) => props.kind === 'container', + styles: { + display: 'grid', + flex: '1 1 auto', + userSelect: 'none', + }, +}; + +const PiecePattern = { applyOn: (props) => props.kind === 'piece', order: 0, style: { @@ -56,17 +48,66 @@ export const PIECE: ProviderPattern = { }, }; +const Main = () => { + return ( + + + + Hello world. + + + Hello world 2. + + + + ); +}; + +render(
); +``` + +#### Align Components + +```tsx +function Main() { + return ( + + + + Hello world + + Hello world + + + ); +} ``` -You can ask why `user-select: none` and here's the answer it's really anoying -navigate to a website where I can select everything even that doesn't meant for -and for that reason it's the same with scrolls they broke our navigation -everywhere when we want it or not and for that reason I have way to control it -into our webapps adding basic reset for our controls: +#### **`Reset CSS`** -```js +In the system offered we count with: -export const RESET: ProviderPattern = { +```tsx +const RESET = { applyOn: 'all', order: 0, style: { @@ -84,83 +125,169 @@ export const RESET: ProviderPattern = { overflow: 'hidden', }, }; +``` + +You'll probably ask why put **`overflow: hidden`** for all sort of component... + +#### **``** + +Something that always broke our navigation is definitely scrolls, when we want +to put it or not. For that reason I think the best solution at all is hide from +everything and show when you want to with: ``. + +Then everytime you want to render something that will grow more than your +avaiable space, like lists: +- **You can select the direction.** +- **Customize colors to match with your style.** +- **Animate: instant, smooth.** + +```tsx showLineNumbers live + props.kind === 'scrollable', + style: (theme) => ({ + '--color': theme.color, + '--highlight': theme.highlight, + }), + })} +> + + + + + + + ``` -But you'll probably ask, what do I do when I need for that reason I have a -component called `` where you can set the direction, animations, -etc. +#### **``** -## Creating your system +Basic with this component you can use a text and align in all directions with +`flex props`: + +```tsx + + Centered + +``` + +#### **``** + +Sometimes you want to hide some component at some screen size: + +```tsx showLineNumbers + + Hello world + +``` + +Now you only will see it at screens bigger than **`702px`**. + +However the element will remain at your `HTML` if you don't want to: + +```tsx showLineNumbers + + Hello world + +``` + +And if you want to be notified when the element will be activate -You can set a css system with JS for example: +```tsx showLineNumbers + + Hello world + +``` -```js +## Creating your system -import { ProviderPattern } from '@lizzelabs/react-harmony'; +You can create your own: -const PIECE: ProviderPattern = { +```tsx live noInline +const PIECE = { applyOn: (props) => props.kind === 'piece', order: 0, style: { - display: 'flex', - flex: '1 1 auto', + display: 'block', userSelect: 'none', }, }; - -const LIST: ProviderPattern = { +const LIST = { applyOn: 'ul', order: 0, style: { listStyle: 'square inside', - paddingLeft: '20px' + paddingLeft: '20px', }, }; - -const LIST_ITEM: ProviderPattern = { - applyOn: 'li', - order: 0, - style: { - color: '#333', - line-height: 1.6 - } +const LIST_ITEM = { + applyOn: 'li', + order: 0, + style: { + color: 'orange', + lineHeight: 1.8, + }, }; -const MyCustomCssSystem = [ - PIECE, - LIST, - LIST_ITEM -]; - - -export const Main = () => { - - return ( - - - - Item 1 - - - - ) - +const MyCustomCssSystem = [PIECE, LIST, LIST_ITEM]; +const Main = () => { + return ( + + + Item 1 + + + ); }; +render(
); ``` +But if you want to use **``** and other components designed for +you should extend from the main system: + ## Compounding Systems You can merge more than one system adding your styles to the main -`HARMONY_SYSTEM`: +`HARMONY_SYSTEM` by importing **`mergeSystems`** look: ```tsx -import { mergeSystems, HARMONY_SYSTEM } from '@lizzelabs/react-harmony'; - interface CustomTheme { color: string; highlight: string; diff --git a/docs/docs/getting-started/theming.mdx b/docs/docs/getting-started/theming.mdx index 52ecb37..2c8be5a 100644 --- a/docs/docs/getting-started/theming.mdx +++ b/docs/docs/getting-started/theming.mdx @@ -46,7 +46,7 @@ export const Theme = { } satisfies MyCustomTheme; ``` -after you need to register into our provider: +after you need to register into provider: ```tsx import { PieceProvider } from '@lizzelabs/react-harmony'; @@ -62,7 +62,7 @@ export const RootApp = () => { ``` simple as that and after you can use into `withStyle` or even at some properties -of piece: +of a piece: ```tsx import { Piece } from '@lizzelabs/react-harmony'; diff --git a/docs/docs/getting-started/withPieceAsContainer.mdx b/docs/docs/getting-started/withPieceAsContainer.mdx index f4db47c..b265fba 100644 --- a/docs/docs/getting-started/withPieceAsContainer.mdx +++ b/docs/docs/getting-started/withPieceAsContainer.mdx @@ -5,9 +5,9 @@ sidebar_label: 'withPieceAsContainer' # πŸ› οΈ withPieceAsContainer -Sometimes you'll want align components, stylish your own, for that reason I have -a simple HOC that encapsulates your component into a piece, turning whatever you -want into a piece: +Sometimes you want to shape or align, your component outside I mean from a +container, page, etc and iIt's usefull do it with a HOC: +**`withPieceAsContainer`** ```tsx interface ButtonProps { @@ -22,10 +22,10 @@ const Button = (props: ButtonProps) => { const ButtonAsPiece = withPieceAsContainer(Button, { // Piece default properties: flex: '1 0 auto', -}) as Button; +}); // highlight-end -//Now i can apply properties from a piece into my custom button. +//Now i can apply properties of a piece into my custom button. const Main = () => { // highlight-start diff --git a/docs/package.json b/docs/package.json index c82877d..cb9ab5c 100644 --- a/docs/package.json +++ b/docs/package.json @@ -19,6 +19,7 @@ "@docusaurus/faster": "3.10.1", "@docusaurus/preset-classic": "3.10.1", "@docusaurus/theme-live-codeblock": "^3.10.1", + "@iframe-resizer/react": "^5.5.9", "@lizzelabs/react-harmony": "link:..", "@mdx-js/react": "^3.0.0", "clsx": "^2.0.0", diff --git a/docs/pnpm-lock.yaml b/docs/pnpm-lock.yaml index 8be45d0..c65385c 100644 --- a/docs/pnpm-lock.yaml +++ b/docs/pnpm-lock.yaml @@ -20,6 +20,9 @@ importers: '@docusaurus/theme-live-codeblock': specifier: ^3.10.1 version: 3.10.1(@docusaurus/faster@3.10.1(@docusaurus/types@3.10.1(@swc/core@1.15.33)(react-dom@19.2.5(react@19.2.5))(react@19.2.5)))(@docusaurus/plugin-content-docs@3.10.1(@docusaurus/faster@3.10.1(@docusaurus/types@3.10.1(@swc/core@1.15.33)(react-dom@19.2.5(react@19.2.5))(react@19.2.5)))(@mdx-js/react@3.1.1(@types/react@19.2.14)(react@19.2.5))(@rspack/core@1.7.11)(@swc/core@1.15.33)(react-dom@19.2.5(react@19.2.5))(react@19.2.5)(typescript@6.0.3))(@mdx-js/react@3.1.1(@types/react@19.2.14)(react@19.2.5))(@rspack/core@1.7.11)(@swc/core@1.15.33)(react-dom@19.2.5(react@19.2.5))(react@19.2.5)(typescript@6.0.3) + '@iframe-resizer/react': + specifier: ^5.5.9 + version: 5.5.9(react-dom@19.2.5(react@19.2.5))(react@19.2.5) '@lizzelabs/react-harmony': specifier: link:.. version: link:.. @@ -1260,6 +1263,15 @@ packages: '@hapi/topo@5.1.0': resolution: {integrity: sha512-foQZKJig7Ob0BMAYBfcJk8d77QtOe7Wo4ox7ff1lQYoNNAb6jwcY1ncdoy2e9wQZzvNy7ODZCYJkK8kzmcAnAg==} + '@iframe-resizer/core@5.5.9': + resolution: {integrity: sha512-HacDQx81pgHlmY48tRogcX02TOXfvjllJzI+xfVYmvEXhxoViyi9yEobhNQEt8Mq6NmrH1vHhz6FRfQ9uBTsjQ==} + + '@iframe-resizer/react@5.5.9': + resolution: {integrity: sha512-PXzQ9m594JsUWjfgk0BIvd9Boow/GSBhViwxlHoHPRsZGsLMqsELvdlcnCEL3acKVl5mDl2KF+hIImA98vPalA==} + peerDependencies: + react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 + react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 + '@jest/schemas@29.6.3': resolution: {integrity: sha512-mo5j5X+jIZmJQveBKeS/clAueipV7KgiX1vMgCxam1RNYiqE1w62n0/tJJnHtjW8ZHcQco5gY85jA3mi0L+nSA==} engines: {node: ^14.15.0 || ^16.10.0 || >=18.0.0} @@ -2193,6 +2205,9 @@ packages: resolution: {integrity: sha512-LElXdjswlqjWrPpJFg1Fx4wpkOCxj1TDHlSV4PlaRxHGWko024xICaa97ZkMfs6DRKlCguiAI+rbXv5GWwXIkg==} hasBin: true + auto-console-group@1.3.0: + resolution: {integrity: sha512-W/G5jy1ZPeVYPyqOVGND7EjbzrsLgRD3s+1QegXfJ7bYlphFxjqG60rviFXWw0d2YCj0Clc7hU5/nTqrBEhBIw==} + autoprefixer@10.5.0: resolution: {integrity: sha512-FMhOoZV4+qR6aTUALKX2rEqGG+oyATvwBt9IIzVR5rMa2HRWPkxf+P+PAJLD1I/H5/II+HuZcBJYEFBpq39ong==} engines: {node: ^10 || ^12 || >=14} @@ -7614,6 +7629,18 @@ snapshots: dependencies: '@hapi/hoek': 9.3.0 + '@iframe-resizer/core@5.5.9': + dependencies: + auto-console-group: 1.3.0 + + '@iframe-resizer/react@5.5.9(react-dom@19.2.5(react@19.2.5))(react@19.2.5)': + dependencies: + '@babel/runtime': 7.29.2 + '@iframe-resizer/core': 5.5.9 + auto-console-group: 1.3.0 + react: 19.2.5 + react-dom: 19.2.5(react@19.2.5) + '@jest/schemas@29.6.3': dependencies: '@sinclair/typebox': 0.27.10 @@ -8668,6 +8695,8 @@ snapshots: astring@1.9.0: {} + auto-console-group@1.3.0: {} + autoprefixer@10.5.0(postcss@8.5.14): dependencies: browserslist: 4.28.2 diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index a5bb0b3..593efc2 100644 --- a/docs/src/css/custom.css +++ b/docs/src/css/custom.css @@ -10,6 +10,11 @@ display: none !important; } +code { + white-space: pre-wrap !important; + word-break: break-all !important; +} + :root { --ifm-color-primary: hsl(226, 22.88%, 40%); --ifm-color-primary-dark: hsl(226, 22.88%, 30%); diff --git a/docs/src/theme/ReactLiveScope/index.tsx b/docs/src/theme/ReactLiveScope/index.tsx index 8ab0e20..2866c06 100644 --- a/docs/src/theme/ReactLiveScope/index.tsx +++ b/docs/src/theme/ReactLiveScope/index.tsx @@ -6,9 +6,13 @@ import { Scrollable, Text, Media, + useStyle, + Styles, + HARMONY_SYSTEM, + mergeSystems, } from '@lizzelabs/react-harmony'; -const ReactLiveScope: unknown = { +export default { React, ...React, Piece, @@ -17,6 +21,8 @@ const ReactLiveScope: unknown = { Scrollable, Text, Media, + Styles, + HARMONY_SYSTEM, + mergeSystems, + useStyle, }; - -export default ReactLiveScope; diff --git a/package.json b/package.json index 4c4d2a4..04442fb 100644 --- a/package.json +++ b/package.json @@ -70,6 +70,11 @@ "import": "./dist/animations.es.js", "require": "./dist/animations.es.js", "types": "./dist/components/animations/index.d.ts" + }, + "./hocs": { + "import": "./dist/hocs.es.js", + "require": "./dist/hocs.es.js", + "types": "./dist/hocs/index.d.ts" } }, "publishConfig": { diff --git a/src/index.ts b/src/index.ts index 3d8001f..8839b55 100644 --- a/src/index.ts +++ b/src/index.ts @@ -3,3 +3,4 @@ export * from './systems'; export * from './types'; export * from './utils'; export * from './hocs'; +export * from './hooks'; diff --git a/src/systems/harmony/container.ts b/src/systems/harmony/container.ts new file mode 100644 index 0000000..0b7c99b --- /dev/null +++ b/src/systems/harmony/container.ts @@ -0,0 +1,12 @@ +/* eslint-disable @typescript-eslint/no-explicit-any */ +import type { ProviderPattern } from '@/components'; + +export const CONTAINER: ProviderPattern = { + applyOn: (props) => props.kind === 'container', + order: 0, + style: { + display: 'grid', + flex: '1 1 auto', + userSelect: 'none', + }, +}; diff --git a/src/systems/harmony/index.ts b/src/systems/harmony/index.ts index ec2d3d1..e02e82f 100644 --- a/src/systems/harmony/index.ts +++ b/src/systems/harmony/index.ts @@ -3,5 +3,13 @@ import { PIECE } from './piece'; import { RESET } from './reset'; import { SCREEN } from './screen'; import { SCROLLABLE } from './scrollable'; +import { CONTAINER } from './container'; -export const HARMONY_SYSTEM = [RESET, PIECE, SCREEN, MEDIA, SCROLLABLE]; +export const HARMONY_SYSTEM = [ + RESET, + CONTAINER, + PIECE, + SCREEN, + MEDIA, + SCROLLABLE, +]; diff --git a/vite.config.ts b/vite.config.ts index c5c450b..f8d2c50 100644 --- a/vite.config.ts +++ b/vite.config.ts @@ -25,6 +25,7 @@ export default defineConfig({ ), screen: resolve(__dirname, 'src/components/screen/index.ts'), scrollable: resolve(__dirname, 'src/components/scrollable/index.ts'), + hocs: resolve(__dirname, 'src/hocs/index.ts'), text: resolve(__dirname, 'src/components/text/index.ts'), systems: resolve(__dirname, 'src/systems/index.ts'), types: resolve(__dirname, 'src/types'),