@pyreon/elements 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+# @pyreon/elements
+
+Foundational UI components for Pyreon with responsive props.
+
+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.
+
+## Features
+
+- **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** — headless trigger+content pattern
+- **Portal** — stub (runtime-dom provides actual portal)
+- **Responsive everything** — single value, array, or breakpoint object on every layout prop
+- **Equal before/after** — `equalBeforeAfter` prop on Element to equalize slot dimensions
+
+## Installation
+
+```bash
+bun add @pyreon/elements
+```
+
+## Components
+
+### Element
+
+The core layout primitive. Renders a three-section flex container with optional beforeContent and afterContent slots around the main content.
+
+```ts
+import { Element } from '@pyreon/elements'
+
+Element({
+  tag: 'button',
+  beforeContent: Icon({ name: 'star' }),
+  afterContent: Icon({ name: 'chevron-right' }),
+  direction: 'inline',
+  alignX: 'center',
+  alignY: 'center',
+  gap: 8,
+  children: 'Click me',
+})
+```
+
+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 | `VNode` | Standard children |
+| content | `VNode` | Alternative to children |
+| label | `VNode` | Alternative to children/content |
+| beforeContent | `VNode` | Content rendered before the main slot |
+| afterContent | `VNode` | 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:
+
+```ts
+Element({
+  contentDirection: 'rows',
+  contentAlignX: 'center',
+  beforeContentAlignY: 'top',
+  afterContentDirection: 'inline',
+})
+```
+
+### Text
+
+Semantic text component with optional paragraph auto-wrapping.
+
+```ts
+import { Text } from '@pyreon/elements'
+
+Text({ tag: 'h1', children: 'Heading' })
+Text({ paragraph: true, children: 'This renders as a p tag.' })
+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 | `VNode` | Text content |
+| css | `ExtendCss` | Extend styling |
+
+### List
+
+Data-driven list renderer with positional metadata.
+
+```ts
+import { List, Element } from '@pyreon/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: true,
+  direction: 'rows',
+  gap: 8,
+  component: Card,
+  data: items,
+})
+```
+
+| Prop | Type | Description |
+| ---- | ---- | ----------- |
+| data | `Array` | Array of strings, numbers, or objects |
+| component | `ComponentFn` | 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 | `ComponentFn` | 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)
+
+### Overlay
+
+Headless trigger+content pattern for dropdowns, tooltips, and modals.
+
+```ts
+import { Overlay } from '@pyreon/elements'
+
+Overlay({
+  openOn: 'click',
+  closeOn: 'clickOutsideContent',
+  align: 'bottom',
+  alignX: 'left',
+  trigger: Button({ label: 'Open menu' }),
+  children: DropdownMenu({}),
+})
+```
+
+### Portal
+
+Stub component — the actual portal implementation is provided by `@pyreon/core`'s runtime-dom.
+
+## Responsive Values
+
+Every layout prop (direction, alignX, alignY, gap, block, equalCols) supports three formats:
+
+```ts
+// 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 |
+| ------- | ------- |
+| @pyreon/core | >= 0.0.1 |
+| @pyreon/reactivity | >= 0.0.1 |
+| @pyreon/ui-core | >= 0.0.1 |
+| @pyreon/unistyle | >= 0.0.1 |
+
+## License
+
+MIT

package/lib/index.d.ts

@@ -0,0 +1,426 @@
+import { Provider } from "@pyreon/unistyle";
+import * as _pyreon_core0 from "@pyreon/core";
+import { ComponentFn, VNodeChild } from "@pyreon/core";
+import { BreakpointKeys, HTMLTags, HTMLTextTags, config, render } from "@pyreon/ui-core";
+import * as _pyreon_reactivity0 from "@pyreon/reactivity";
+
+//#region src/types.d.ts
+type ExtractNullableKeys<T> = { [P in keyof T as T[P] extends null | undefined ? never : P]: T[P] };
+type Id<T> = T extends infer U ? { [K in keyof U]: U[K] } : never;
+type SpreadTwo<L, R> = Id<Pick<L, Exclude<keyof L, keyof R>> & R>;
+type Spread<A extends readonly [...any]> = A extends [infer L, ...infer R] ? SpreadTwo<L, Spread<R>> : unknown;
+type MergeTypes<A extends readonly [...any]> = ExtractNullableKeys<Spread<A>>;
+type InnerRef = HTMLElement | ((el: HTMLElement | null) => void) | null;
+type CssCallback = (css: typeof config.css) => ReturnType<typeof css>;
+type Css = CssCallback | ReturnType<typeof config.css> | string;
+type Content = Parameters<typeof render>["0"];
+type ContentAlignX = "left" | "center" | "right" | "spaceBetween" | "spaceAround" | "block";
+type ContentAlignY = "top" | "center" | "bottom" | "spaceBetween" | "spaceAround" | "block";
+type ContentDirection = "inline" | "rows" | "reverseInline" | "reverseRows";
+type ContentBoolean = boolean;
+type ContentSimpleValue = string | number;
+type AlignY = ContentAlignY | ContentAlignY[] | Partial<Record<BreakpointKeys, ContentAlignY>>;
+type AlignX = ContentAlignX | ContentAlignX[] | Partial<Record<BreakpointKeys, ContentAlignX>>;
+type Direction = ContentDirection | ContentDirection[] | Partial<Record<BreakpointKeys, ContentDirection>>;
+type ResponsiveBoolType = ContentBoolean | ContentBoolean[] | Partial<Record<BreakpointKeys, ContentBoolean>>;
+type Responsive = ContentSimpleValue | ContentSimpleValue[] | Partial<Record<BreakpointKeys, number | string>>;
+type ExtendCss = Css | Css[] | Partial<Record<BreakpointKeys, Css>>;
+type PyreonComponent<P extends Record<string, any> = Record<string, unknown>> = ComponentFn<P> & PyreonStatic;
+interface PyreonStatic {
+  displayName?: string | undefined;
+  pkgName?: string;
+  PYREON__COMPONENT?: `@pyreon/${string}`;
+}
+//#endregion
+//#region src/Element/types.d.ts
+type Props = Partial<{
+  /**
+   * Valid HTML Tag
+   */
+  tag: HTMLTags;
+  /**
+   * Ref prop, alternative to `ref`
+   */
+  innerRef: InnerRef;
+  /**
+   * Valid `children`
+   */
+  children: Content;
+  /**
+   * Alternative prop to `children`
+   * It is recommended to pass only one of `children`, `content` or `label` props
+   *
+   * The prioritization of rendering is following: `children` → `content` → `label`
+   */
+  content: Content;
+  /**
+   * Alternative prop to `children`
+   * It is recommended to pass only one of `children`, `content` or `label` props
+   *
+   * The prioritization of rendering is following: `children` → `content` → `label`
+   */
+  label: Content;
+  /**
+   * Valid `children` to be rendered inside _beforeContent_ wrapper
+   */
+  beforeContent: Content;
+  /**
+   * Valid `children` to be rendered inside _afterContent_ wrapper
+   */
+  afterContent: Content;
+  /**
+   * A boolean type to define whether **Element** should behave
+   * as an inline or block element (`flex` vs. `inline-flex`)
+   */
+  block: ResponsiveBoolType;
+  /**
+   * A boolean type to define whether inner wrappers should be equal
+   * (have the same width or height)
+   */
+  equalCols: ResponsiveBoolType;
+  /**
+   * When true, measures the `beforeContent` and `afterContent` slot wrappers
+   * after render and sets both to the larger dimension so they match.
+   */
+  equalBeforeAfter: boolean;
+  /**
+   * Defines a `gap` spacing between inner wrappers
+   */
+  gap: Responsive;
+  /**
+   * Defines direction of inner wrappers
+   */
+  direction: Direction;
+  /**
+   * Defines flow of `children` elements within its inner wrapper.
+   */
+  contentDirection: Direction;
+  /**
+   * Defines flow of `beforeContent` elements within its inner wrapper.
+   */
+  beforeContentDirection: Direction;
+  /**
+   * Defines flow of `afterContent` elements within its inner wrapper.
+   */
+  afterContentDirection: Direction;
+  /**
+   * Define alignment horizontally.
+   */
+  alignX: AlignX;
+  /**
+   * Defines how `content` children are aligned horizontally.
+   */
+  contentAlignX: AlignX;
+  /**
+   * Defines how `beforeContent` children are aligned horizontally.
+   */
+  beforeContentAlignX: AlignX;
+  /**
+   * Defines how `afterContent` children are aligned horizontally.
+   */
+  afterContentAlignX: AlignX;
+  /**
+   * Define alignment vertically.
+   */
+  alignY: AlignY;
+  /**
+   * Defines how `content` children are aligned vertically.
+   */
+  contentAlignY: AlignY;
+  /**
+   * Defines how `beforeContent` children are aligned vertically.
+   */
+  beforeContentAlignY: AlignY;
+  /**
+   * Defines how `afterContent` children are aligned vertically.
+   */
+  afterContentAlignY: AlignY;
+  /**
+   * `dangerouslySetInnerHTML` prop
+   */
+  dangerouslySetInnerHTML: {
+    __html: string;
+  };
+  /**
+   * An additional prop for extending styling of the **root** wrapper element
+   */
+  css: ExtendCss;
+  /**
+   * An additional prop for extending styling of the **content** wrapper element.
+   */
+  contentCss: ExtendCss;
+  /**
+   * An additional prop for extending styling of the **beforeContent** wrapper element.
+   */
+  beforeContentCss: ExtendCss;
+  /**
+   * An additional prop for extending styling of the **afterContent** wrapper element.
+   */
+  afterContentCss: ExtendCss;
+}>;
+type PyreonElement<P extends Record<string, unknown> = Record<string, unknown>> = ComponentFn<Props & P> & PyreonStatic;
+//#endregion
+//#region src/Element/component.d.ts
+declare const Component: PyreonElement;
+//#endregion
+//#region src/helpers/Iterator/types.d.ts
+type MaybeNull = undefined | null;
+type TObj = Record<string, unknown>;
+type SimpleValue = string | number;
+type ObjectValue = Partial<{
+  id: SimpleValue;
+  key: SimpleValue;
+  itemId: SimpleValue;
+  component: ElementType;
+}> & Record<string, unknown>;
+type ElementType<T extends Record<string, unknown> = any> = ComponentFn<T> | HTMLTags;
+type ExtendedProps = {
+  index: number;
+  first: boolean;
+  last: boolean;
+  odd: boolean;
+  even: boolean;
+  position: number;
+};
+type PropsCallback = TObj | ((itemProps: Record<string, never> | Record<string, SimpleValue> | ObjectValue, extendedProps: ExtendedProps) => TObj);
+type Props$1 = Partial<{
+  /**
+   * Valid children
+   */
+  children: VNodeChild;
+  /**
+   * Array of data passed to `component` prop
+   */
+  data: Array<SimpleValue | ObjectValue | MaybeNull>;
+  /**
+   * A component to be rendered within list
+   */
+  component: ElementType;
+  /**
+   * Defines name of the prop to be passed to the iteration component
+   * when **data** prop is type of `string[]`, `number[]` or combination
+   * of both. Otherwise ignored.
+   */
+  valueName: string;
+  /**
+   * A component to be rendered within list. `wrapComponent`
+   * wraps `component`. Therefore it can be used to enhance the behavior
+   * of the list component
+   */
+  wrapComponent: ElementType;
+  /**
+   * Extension of **item** `component` props to be passed
+   */
+  itemProps: PropsCallback;
+  /**
+   * Extension of **item** `wrapComponent` props to be passed
+   */
+  wrapProps?: PropsCallback;
+  /**
+   * Extension of **item** `wrapComponent` props to be passed
+   */
+  itemKey?: keyof ObjectValue | ((item: SimpleValue | Omit<ObjectValue, "component">, index: number) => SimpleValue);
+}>;
+//#endregion
+//#region src/helpers/Iterator/component.d.ts
+declare const _default: ((props: Props$1) => VNodeChild) & {
+  isIterator: true;
+  RESERVED_PROPS: readonly ["children", "component", "wrapComponent", "data", "itemKey", "valueName", "itemProps", "wrapProps"];
+};
+//#endregion
+//#region src/List/component.d.ts
+type ListProps = {
+  /**
+   * A boolean value. When set to `false`, component returns fragment.
+   * When set to `true`, component returns as the **root** element `Element`
+   * component.
+   */
+  rootElement?: boolean;
+  /**
+   * Label prop from `Element` component is being ignored.
+   */
+  label: never;
+  /**
+   * Content prop from `Element` component is being ignored.
+   */
+  content: never;
+};
+type Props$2 = MergeTypes<[Props$1, ListProps]>;
+declare const Component$1: PyreonElement<Props$2>;
+//#endregion
+//#region src/Overlay/context.d.ts
+interface OverlayContext {
+  blocked: boolean | (() => boolean);
+  setBlocked: () => void;
+  setUnblocked: () => void;
+}
+declare const Component$3: ({
+  children,
+  blocked,
+  setBlocked,
+  setUnblocked
+}: OverlayContext & {
+  children: VNodeChild;
+}) => any;
+//#endregion
+//#region src/Overlay/useOverlay.d.ts
+/**
+ * Core hook powering the Overlay component. Manages open/close state, DOM
+ * event listeners (click, hover, scroll, resize, ESC key), and dynamic
+ * positioning of overlay content relative to its trigger. Supports dropdown,
+ * tooltip, popover, and modal types with automatic edge-of-viewport flipping.
+ * Event handlers are throttled for performance, and nested overlay blocking
+ * is coordinated through the overlay context.
+ */
+type Align$1 = "bottom" | "top" | "left" | "right";
+type AlignX$2 = "left" | "center" | "right";
+type AlignY$2 = "bottom" | "top" | "center";
+type UseOverlayProps = Partial<{
+  isOpen: boolean;
+  openOn: "click" | "hover" | "manual";
+  closeOn: "click" | "clickOnTrigger" | "clickOutsideContent" | "hover" | "manual";
+  type: "dropdown" | "tooltip" | "popover" | "modal" | "custom";
+  position: "absolute" | "fixed" | "relative" | "static";
+  align: Align$1;
+  alignX: AlignX$2;
+  alignY: AlignY$2;
+  offsetX: number;
+  offsetY: number;
+  throttleDelay: number;
+  parentContainer: HTMLElement | null;
+  closeOnEsc: boolean;
+  hoverDelay: number;
+  disabled: boolean;
+  onOpen: () => void;
+  onClose: () => void;
+}>;
+declare const useOverlay: ({
+  isOpen,
+  openOn,
+  closeOn,
+  type,
+  position,
+  align,
+  alignX: propAlignX,
+  alignY: propAlignY,
+  offsetX,
+  offsetY,
+  throttleDelay,
+  parentContainer,
+  closeOnEsc,
+  hoverDelay,
+  disabled,
+  onOpen,
+  onClose
+}?: Partial<UseOverlayProps>) => {
+  triggerRef: (node: HTMLElement | null) => void;
+  contentRef: (node: HTMLElement | null) => void;
+  active: _pyreon_reactivity0.Signal<boolean>;
+  align: Align$1;
+  alignX: _pyreon_reactivity0.Signal<AlignX$2>;
+  alignY: _pyreon_reactivity0.Signal<AlignY$2>;
+  showContent: () => void;
+  hideContent: () => void;
+  blocked: () => boolean;
+  setBlocked: () => void;
+  setUnblocked: () => void;
+  setupListeners: () => () => void;
+  Provider: ({
+    children,
+    blocked,
+    setBlocked,
+    setUnblocked
+  }: OverlayContext & {
+    children: _pyreon_core0.VNodeChild;
+  }) => any;
+};
+//#endregion
+//#region src/Overlay/component.d.ts
+type Align = "bottom" | "top" | "left" | "right";
+type AlignX$1 = "left" | "center" | "right";
+type AlignY$1 = "bottom" | "top" | "center";
+type TriggerRenderer = (props: Partial<{
+  active: boolean;
+  showContent: () => void;
+  hideContent: () => void;
+}>) => VNodeChild;
+type ContentRenderer = (props: Partial<{
+  active: boolean;
+  showContent: () => void;
+  hideContent: () => void;
+  align: Align;
+  alignX: AlignX$1;
+  alignY: AlignY$1;
+}>) => VNodeChild;
+type Props$3 = {
+  children: ContentRenderer | Content;
+  trigger: TriggerRenderer | Content;
+  DOMLocation?: HTMLElement;
+  triggerRefName?: string;
+  contentRefName?: string;
+} & UseOverlayProps;
+declare const Component$2: PyreonComponent<Props$3>;
+//#endregion
+//#region src/Portal/component.d.ts
+interface Props$4 {
+  /**
+   * Defines a HTML DOM where children to be appended.
+   */
+  DOMLocation?: HTMLElement;
+  /**
+   * Children to be rendered within **Portal** component.
+   */
+  children: VNodeChild;
+  /**
+   * Valid HTML Tag
+   */
+  tag?: string;
+}
+declare const Component$4: PyreonComponent<Props$4>;
+//#endregion
+//#region src/Text/component.d.ts
+type Props$5 = Partial<{
+  /**
+   * Label can be used instead of children for inline syntax. But **children** prop takes a precedence
+   */
+  label: VNodeChild;
+  /**
+   * Children to be rendered within **Text** component.
+   */
+  children: VNodeChild;
+  /**
+   * Defines whether should behave as a block text element. Automatically adds **p** HTML tag
+   */
+  paragraph: boolean;
+  /**
+   * Defines what kind of HTML tag should be rendered
+   */
+  tag: HTMLTextTags;
+  /**
+   * If an additional styling needs to be added, it can be do so via injecting styles using this property.
+   */
+  css: ExtendCss;
+}> & Record<string, unknown>;
+declare const Component$5: PyreonComponent<Props$5> & {
+  isText?: true;
+};
+//#endregion
+//#region src/Util/component.d.ts
+interface Props$6 {
+  /**
+   * Children to be rendered within **Util** component.
+   */
+  children: VNodeChild;
+  /**
+   * Class name(s) to be added to children component.
+   */
+  className?: string | string[] | undefined;
+  /**
+   * Style property to extend children component inline styles
+   */
+  style?: Record<string, unknown> | undefined;
+}
+declare const Component$6: PyreonComponent<Props$6>;
+//#endregion
+export { type AlignX, type AlignY, type Content, type ContentBoolean, type Direction, Component as Element, type Props as ElementProps, type ElementType, type ExtendCss, type ExtendedProps, type InnerRef, _default as Iterator, type Props$1 as IteratorProps, Component$1 as List, type Props$2 as ListProps, type ObjectValue, Component$2 as Overlay, type Props$3 as OverlayProps, Component$3 as OverlayProvider, Component$4 as Portal, type Props$4 as PortalProps, type PropsCallback, Provider, type PyreonElement, type PyreonStatic, type Responsive, type ResponsiveBoolType, type SimpleValue, Component$5 as Text, type Props$5 as TextProps, type UseOverlayProps, Component$6 as Util, type Props$6 as UtilProps, useOverlay };
+//# sourceMappingURL=index2.d.ts.map