@vitus-labs/elements 1.2.2 → 1.2.3-alpha.3

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Vit Bokisch
+Copyright (c) 2023-present Vit Bokisch
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,100 +1,313 @@
-<div align="center">
-  <a href="https://vitus-labs.com/docs/ui-system/elements">
-    <img src="https://github.com/vitus-labs/ui-system/blob/master/packages/elements/logo.png" alt="Elements" height="150" />
-  </a>
-</div>
+# @vitus-labs/elements
 
-# Getting Started
+Layout primitives for React with responsive props.
 
-Elements are a package of patterns that should cover very common
-and frequent use-cases, so you don't have to repeat yourself again
-and again. Elements are a package of patterns that should cover very
-common and frequent use-cases, so you don't have to repeat yourself
-again and again.
+[![npm](https://img.shields.io/npm/v/@vitus-labs/elements)](https://www.npmjs.com/package/@vitus-labs/elements)
+[![license](https://img.shields.io/npm/l/@vitus-labs/elements)](https://github.com/vitus-labs/ui-system/blob/main/LICENSE)
 
-Full documentation is at [https:vitus-labs.com/](https://vitus-labs.com/docs/ui-system/elements)
+Five composable components for building buttons, cards, lists, dropdowns, tooltips, and modals. Every layout prop is responsive — pass a single value, a mobile-first array, or a breakpoint object.
 
-## Motivation
+## Features
 
-The goal is to cover many repeatable use-cases of writing code and make
-a bunch of components that would solve this. You shouldn't focus on some
-specifics of CSS or thinking about HTML validation or so. The goal is to
-make configurable components so you can focus on your goals and business
-value.
+- **Element** — three-section flex layout (beforeContent / content / afterContent)
+- **Text** — semantic text rendering with auto paragraph wrapping
+- **List** — data-driven rendering with positional metadata (first, last, odd, even)
+- **Overlay** — portal-based positioning for dropdowns, tooltips, and modals with auto-flip
+- **Portal** — React Portal wrapper for DOM appending
+- **Util** — non-rendering utility for injecting className and style
+- **Responsive everything** — single value, array, or breakpoint object on every layout prop
+- **Selection state** — `withActiveState` HOC for single/multi item selection on List
 
-### Components available in the package
+## Installation
+
+```bash
+npm install @vitus-labs/elements @vitus-labs/core @vitus-labs/unistyle styled-components
+```
+
+## Components
 
 ### Element
 
-**Element** is a simple component for aligning simple elements vertically/horizontally.
-This might help add some additional elements like loading icon to button, input
-element symbol, or validation element. Which leads to repeatable patterns.
-All these things and much more can be covered by this component.
+The core layout primitive. Renders a three-section flex container with optional beforeContent and afterContent slots around the main content.
 
-### List
+```tsx
+import { Element } from '@vitus-labs/elements'
+
+// Simple button with icon before and chevron after
+<Element
+  tag="button"
+  beforeContent={<Icon name="star" />}
+  afterContent={<Icon name="chevron-right" />}
+  direction="inline"
+  alignX="center"
+  alignY="center"
+  gap={8}
+>
+  Click me
+</Element>
+```
+
+When only content is present (no beforeContent/afterContent), Element optimizes by skipping the inner wrapper layer.
+
+**Content props** (rendered in priority order: children > content > label):
+
+| Prop | Type | Description |
+| ---- | ---- | ----------- |
+| children | `ReactNode` | Standard React children |
+| content | `ReactNode` | Alternative to children |
+| label | `ReactNode` | Alternative to children/content |
+| beforeContent | `ReactNode` | Content rendered before the main slot |
+| afterContent | `ReactNode` | Content rendered after the main slot |
+
+**Layout props** (all responsive):
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| tag | `HTMLTags` | `'div'` | HTML element tag |
+| block | `boolean` | — | `flex` vs `inline-flex` |
+| direction | `Direction` | `'inline'` | `'inline'` \| `'rows'` \| `'reverseInline'` \| `'reverseRows'` |
+| alignX | `AlignX` | `'left'` | Horizontal alignment |
+| alignY | `AlignY` | `'center'` | Vertical alignment |
+| gap | `number` | — | Gap between content sections |
+| equalCols | `boolean` | — | Equal width/height for before/after |
+
+Each section (content, beforeContent, afterContent) has its own direction, alignX, and alignY props prefixed with the section name:
+
+```tsx
+<Element
+  contentDirection="rows"
+  contentAlignX="center"
+  beforeContentAlignY="top"
+  afterContentDirection="inline"
+/>
+```
+
+**CSS extension props:**
 
-Another use case is rendering simple lists of data. If you are tired of using
-the `map` function again and again this component is here to cover it for you.
+| Prop | Description |
+| ---- | ----------- |
+| css | Extend root wrapper styling |
+| contentCss | Extend content wrapper styling |
+| beforeContentCss | Extend beforeContent wrapper styling |
+| afterContentCss | Extend afterContent wrapper styling |
+
+CSS props accept strings, template literals, `css` tagged templates, or callbacks.
 
 ### Text
 
-Simple component for s or any inline text element like strong, small and so on.
+Semantic text component with optional paragraph auto-wrapping.
+
+```tsx
+import { Text } from '@vitus-labs/elements'
+
+<Text tag="h1">Heading</Text>
+<Text paragraph>This renders as a p tag.</Text>
+<Text tag="strong" label="Bold text" />
+```
+
+| Prop | Type | Description |
+| ---- | ---- | ----------- |
+| tag | `HTMLTextTags` | `'h1'`–`'h6'`, `'p'`, `'span'`, `'strong'`, `'em'`, etc. |
+| paragraph | `boolean` | Shorthand for `tag="p"` |
+| children / label | `ReactNode` | Text content |
+| css | `ExtendCss` | Extend styling |
+
+### List
+
+Data-driven list renderer with Iterator pattern.
+
+```tsx
+import { List, Element } from '@vitus-labs/elements'
+
+// Simple string data
+<List
+  component={Element}
+  data={['Apple', 'Banana', 'Cherry']}
+  valueName="label"
+/>
+
+// Object data with positional metadata
+<List
+  component={ListItem}
+  data={[{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]}
+  itemKey="id"
+  itemProps={(item, { first, last, odd, even, index }) => ({
+    highlighted: first,
+    separator: !last,
+  })}
+/>
+
+// With root Element wrapper
+<List
+  rootElement
+  direction="rows"
+  gap={8}
+  component={Card}
+  data={items}
+/>
+```
+
+| Prop | Type | Description |
+| ---- | ---- | ----------- |
+| data | `Array` | Array of strings, numbers, or objects |
+| component | `ComponentType` | Component to render for each item |
+| valueName | `string` | Prop name for scalar values (default: `'children'`) |
+| itemKey | `string \| function` | Key extraction for list items |
+| itemProps | `object \| function` | Extra props injected into each item |
+| wrapComponent | `ComponentType` | Wrapper around each item |
+| rootElement | `boolean` | Wrap list in an Element (enables direction, gap, etc.) |
+
+**Positional metadata** passed to `itemProps` callback:
+
+`index`, `first`, `last`, `odd`, `even`, `position` (1-based)
+
+### withActiveState
+
+HOC that adds selection state management to List.
+
+```tsx
+import { List, withActiveState } from '@vitus-labs/elements'
+
+const SelectableList = withActiveState(List)
+
+<SelectableList
+  type="single"
+  component={ListItem}
+  data={items}
+  activeItems="item-1"
+/>
+
+<SelectableList
+  type="multi"
+  component={ListItem}
+  data={items}
+  activeItems={['item-1', 'item-3']}
+  activeItemRequired
+/>
+```
+
+Each item receives: `active`, `handleItemActive`, `setItemActive`, `unsetItemActive`, `toggleItemActive`.
 
 ### Overlay
 
-**Overlay** is a component that might help you building modal windows, dropdowns,
-tooltips, popovers, etc. It's quite configurable so you can align elements
-the way you like without any extra effort.
+Portal-based overlay with intelligent positioning and event management.
 
-### Portal
+```tsx
+import { Overlay } from '@vitus-labs/elements'
 
-**Portal** is just a common Reat Portal component to be used to append any elements to DOM.
+// Dropdown
+<Overlay
+  openOn="click"
+  closeOn="clickOutsideContent"
+  align="bottom"
+  alignX="left"
+  trigger={<Button label="Open menu" />}
+>
+  <DropdownMenu />
+</Overlay>
 
-## Installation
+// Tooltip
+<Overlay
+  openOn="hover"
+  closeOn="hover"
+  align="top"
+  alignX="center"
+  offsetY={8}
+  trigger={<span>Hover me</span>}
+>
+  <Tooltip>Helpful text</Tooltip>
+</Overlay>
+```
 
-You can install it with your preferred tool (`yarn` or `npm`).
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| trigger | `ReactNode \| function` | — | The triggering element |
+| children | `ReactNode \| function` | — | Overlay content |
+| openOn | `'click' \| 'hover' \| 'manual'` | `'click'` | How to open |
+| closeOn | `'click' \| 'clickOnTrigger' \| 'clickOutsideContent' \| 'hover' \| 'manual'` | `'click'` | How to close |
+| type | `'dropdown' \| 'tooltip' \| 'popover' \| 'modal' \| 'custom'` | — | Positioning preset |
+| align | `'top' \| 'bottom' \| 'left' \| 'right'` | — | Primary alignment relative to trigger |
+| alignX | `'left' \| 'center' \| 'right'` | — | Horizontal alignment |
+| alignY | `'top' \| 'center' \| 'bottom'` | — | Vertical alignment |
+| offsetX / offsetY | `number` | `0` | Margin from trigger |
+| closeOnEsc | `boolean` | `true` | Close on Escape key |
+| disabled | `boolean` | `false` | Disable open/close |
+| onOpen / onClose | `() => void` | — | Lifecycle callbacks |
 
-```powershell
-# with yarn
-yarn add @vitus-labs/elements @vitus-labs/core
+Overlay auto-flips when content hits the viewport edge. Positioning is throttled for performance.
 
-# or with npm
-npm install @vitus-labs/elements @vitus-labs/core
+When trigger or children are render functions, they receive callbacks:
+
+```tsx
+<Overlay
+  openOn="manual"
+  trigger={({ showContent, active, ref }) => (
+    <button ref={ref} onClick={showContent}>
+      {active ? 'Close' : 'Open'}
+    </button>
+  )}
+>
+  {({ hideContent, align, ref }) => (
+    <div ref={ref}>
+      <button onClick={hideContent}>Close</button>
+    </div>
+  )}
+</Overlay>
 ```
 
-## Dependencies
+### Portal
 
-Elements depends on the following packages which need to be installed as well.
+React Portal wrapper for appending content to a specific DOM location.
 
-| Package          | version      |
-| ---------------- | ------------ |
-| react            | >= 16.7      |
-| @vitus-labs/core | same version |
+```tsx
+import { Portal } from '@vitus-labs/elements'
 
-## Code examples
+<Portal>
+  <div>Rendered at document.body</div>
+</Portal>
 
-```jsx
-import React from 'react'
-import { Element } from '@vitus-labs/elements'
-import Loading from './any-react-component'
-
-const Element = () => (
-  <Element
-    tag="button"
-    label="This is a label"
-    contentAlignX="left"
-    contentAlignY="center"
-    beforeContent={Loading}
-  />
-)
+<Portal DOMLocation={document.getElementById('modal-root')}>
+  <div>Rendered at #modal-root</div>
+</Portal>
 ```
 
-```jsx
-import React from 'react'
-import { List, Element } from '@vitus-labs/elements'
+### Util
 
-const data = [{ label: 'a' }, { label: 'b' }, { label: 'c' }, { label: 'd' }]
-return <List data={data} component={Element} />
+Non-rendering utility that injects className and style into its child.
+
+```tsx
+import { Util } from '@vitus-labs/elements'
+
+<Util className="custom-class" style={{ color: 'red' }}>
+  <div>Receives className and style props</div>
+</Util>
 ```
 
-It's cool, right? So, check out more examples and happy coding!
+## Responsive Values
+
+Every layout prop (direction, alignX, alignY, gap, block, equalCols) supports three formats:
+
+```tsx
+// Single value — all breakpoints
+<Element direction="inline" />
+
+// Array — mobile-first, maps to breakpoints by position
+<Element direction={['rows', 'inline']} />
+
+// Object — explicit breakpoints
+<Element direction={{ xs: 'rows', md: 'inline', lg: 'inline' }} />
+```
+
+## Peer Dependencies
+
+| Package | Version |
+| ------- | ------- |
+| react | >= 19 |
+| react-dom | >= 19 |
+| @vitus-labs/core | * |
+| @vitus-labs/unistyle | * |
+| styled-components | >= 6 |
+
+## License
+
+MIT