@pyreon/elements 0.11.1 → 0.11.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/elements",
-  "version": "0.11.1",
+  "version": "0.11.3",
   "repository": {
     "type": "git",
     "url": "https://github.com/pyreon/pyreon",
@@ -24,7 +24,8 @@
     "!lib/**/*.map",
     "!lib/analysis",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "src"
   ],
   "engines": {
     "node": ">= 22"
@@ -43,13 +44,13 @@
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@pyreon/core": "^0.11.1",
-    "@pyreon/reactivity": "^0.11.1",
-    "@pyreon/ui-core": "^0.11.1",
-    "@pyreon/unistyle": "^0.11.1"
+    "@pyreon/core": "^0.11.3",
+    "@pyreon/reactivity": "^0.11.3",
+    "@pyreon/ui-core": "^0.11.3",
+    "@pyreon/unistyle": "^0.11.3"
   },
   "devDependencies": {
     "@vitus-labs/tools-rolldown": "^1.15.3",
-    "@pyreon/typescript": "^0.11.1"
+    "@pyreon/typescript": "^0.11.3"
   }
 }

package/src/Element/component.tsx

@@ -0,0 +1,211 @@
+/**
+ * Core building block of the elements package. Renders a three-section layout
+ * (beforeContent / content / afterContent) inside a flex Wrapper. When only
+ * content is present, the Wrapper inherits content-level alignment directly
+ * to avoid an unnecessary nesting layer. Handles HTML-specific edge cases
+ * like void elements (input, img) and inline elements (span, a) by
+ * skipping children or switching sub-tags accordingly.
+ */
+
+import { onMount } from "@pyreon/core"
+import { render } from "@pyreon/ui-core"
+import { PKG_NAME } from "../constants"
+import { Content, Wrapper } from "../helpers"
+import type { PyreonElement } from "./types"
+import { getShouldBeEmpty, isInlineElement } from "./utils"
+
+const equalize = (el: HTMLElement, direction: unknown) => {
+  const beforeEl = el.firstElementChild as HTMLElement | null
+  const afterEl = el.lastElementChild as HTMLElement | null
+
+  if (beforeEl && afterEl && beforeEl !== afterEl) {
+    const type: "height" | "width" = direction === "rows" ? "height" : "width"
+    const prop = type === "height" ? "offsetHeight" : "offsetWidth"
+    const beforeSize = beforeEl[prop]
+    const afterSize = afterEl[prop]
+
+    if (Number.isInteger(beforeSize) && Number.isInteger(afterSize)) {
+      const maxSize = `${Math.max(beforeSize, afterSize)}px`
+      beforeEl.style[type] = maxSize
+      afterEl.style[type] = maxSize
+    }
+  }
+}
+
+const defaultDirection = "inline"
+const defaultContentDirection = "rows"
+const defaultAlignX = "left"
+const defaultAlignY = "center"
+
+const Component: PyreonElement = ({
+  innerRef,
+  tag,
+  label,
+  content,
+  children,
+  beforeContent,
+  afterContent,
+  equalBeforeAfter,
+
+  block,
+  equalCols,
+  gap,
+
+  direction,
+  alignX = defaultAlignX,
+  alignY = defaultAlignY,
+
+  css,
+  contentCss,
+  beforeContentCss,
+  afterContentCss,
+
+  contentDirection = defaultContentDirection,
+  contentAlignX = defaultAlignX,
+  contentAlignY = defaultAlignY,
+
+  beforeContentDirection = defaultDirection,
+  beforeContentAlignX = defaultAlignX,
+  beforeContentAlignY = defaultAlignY,
+
+  afterContentDirection = defaultDirection,
+  afterContentAlignX = defaultAlignX,
+  afterContentAlignY = defaultAlignY,
+
+  ref,
+  ...props
+}) => {
+  // --------------------------------------------------------
+  // check if should render only single element
+  // --------------------------------------------------------
+  const shouldBeEmpty = !!props.dangerouslySetInnerHTML || getShouldBeEmpty(tag)
+
+  // --------------------------------------------------------
+  // if not single element, calculate values
+  // --------------------------------------------------------
+  const isSimpleElement = !beforeContent && !afterContent
+  const CHILDREN = children ?? content ?? label
+
+  const isInline = isInlineElement(tag)
+  const SUB_TAG = isInline ? "span" : undefined
+
+  // --------------------------------------------------------
+  // direction & alignX & alignY calculations
+  // --------------------------------------------------------
+  let wrapperDirection: typeof direction = direction
+  let wrapperAlignX: typeof alignX = alignX
+  let wrapperAlignY: typeof alignY = alignY
+
+  if (isSimpleElement) {
+    if (contentDirection) wrapperDirection = contentDirection
+    if (contentAlignX) wrapperAlignX = contentAlignX
+    if (contentAlignY) wrapperAlignY = contentAlignY
+  } else if (direction) {
+    wrapperDirection = direction
+  } else {
+    wrapperDirection = defaultDirection
+  }
+
+  // --------------------------------------------------------
+  // equalBeforeAfter: measure & equalize slot dimensions
+  // --------------------------------------------------------
+  let equalizeRef: HTMLElement | null = null
+  const externalRef = ref ?? innerRef
+
+  const mergedRef = (node: HTMLElement | null) => {
+    equalizeRef = node
+    if (typeof externalRef === "function") externalRef(node)
+    else if (externalRef != null) {
+      ;(externalRef as unknown as { current: HTMLElement | null }).current = node
+    }
+  }
+
+  if (equalBeforeAfter && beforeContent && afterContent) {
+    onMount(() => {
+      if (equalizeRef) equalize(equalizeRef, direction)
+      return undefined
+    })
+  }
+
+  // --------------------------------------------------------
+  // common wrapper props
+  // --------------------------------------------------------
+  const WRAPPER_PROPS = {
+    ref: mergedRef,
+    extendCss: css,
+    tag,
+    block,
+    direction: wrapperDirection,
+    alignX: wrapperAlignX,
+    alignY: wrapperAlignY,
+    as: undefined, // reset styled-components `as` prop
+  }
+
+  // --------------------------------------------------------
+  // return simple/empty element like input or image etc.
+  // --------------------------------------------------------
+  if (shouldBeEmpty) {
+    return <Wrapper {...props} {...WRAPPER_PROPS} />
+  }
+
+  return (
+    <Wrapper {...props} {...WRAPPER_PROPS} isInline={isInline}>
+      {beforeContent && (
+        <Content
+          tag={SUB_TAG}
+          contentType="before"
+          parentDirection={wrapperDirection}
+          extendCss={beforeContentCss}
+          direction={beforeContentDirection}
+          alignX={beforeContentAlignX}
+          alignY={beforeContentAlignY}
+          equalCols={equalCols}
+          gap={gap}
+        >
+          {beforeContent}
+        </Content>
+      )}
+
+      {isSimpleElement ? (
+        render(CHILDREN)
+      ) : (
+        <Content
+          tag={SUB_TAG}
+          contentType="content"
+          parentDirection={wrapperDirection}
+          extendCss={contentCss}
+          direction={contentDirection}
+          alignX={contentAlignX}
+          alignY={contentAlignY}
+          equalCols={equalCols}
+        >
+          {CHILDREN}
+        </Content>
+      )}
+
+      {afterContent && (
+        <Content
+          tag={SUB_TAG}
+          contentType="after"
+          parentDirection={wrapperDirection}
+          extendCss={afterContentCss}
+          direction={afterContentDirection}
+          alignX={afterContentAlignX}
+          alignY={afterContentAlignY}
+          equalCols={equalCols}
+          gap={gap}
+        >
+          {afterContent}
+        </Content>
+      )}
+    </Wrapper>
+  )
+}
+
+const name = `${PKG_NAME}/Element` as const
+
+Component.displayName = name
+Component.pkgName = PKG_NAME
+Component.PYREON__COMPONENT = name
+
+export default Component

package/src/Element/constants.ts

@@ -0,0 +1,96 @@
+/** Props consumed by Element that should not be forwarded to the underlying DOM node. */
+export const RESERVED_PROPS = [
+  "innerRef",
+  "tag",
+  "block",
+  "label",
+  "children",
+  "beforeContent",
+  "afterContent",
+
+  "equalCols",
+  "vertical",
+  "direction",
+  "alignX",
+  "alignY",
+
+  "css",
+  "contentCss",
+  "beforeContentCss",
+  "afterContentCss",
+
+  "contentDirection",
+  "contentAlignX",
+  "contentAlignY",
+
+  "beforeContentDirection",
+  "beforeContentAlignX",
+  "beforeContentAlignY",
+
+  "afterContentDirection",
+  "afterContentAlignX",
+  "afterContentAlignY",
+] as const
+
+/**
+ * HTML tags that are inline-level by default. When Element renders one of
+ * these tags, child Content wrappers use `span` instead of `div` to
+ * preserve valid HTML nesting.
+ */
+export const INLINE_ELEMENTS = {
+  span: true,
+  a: true,
+  button: true,
+  input: true,
+  label: true,
+  select: true,
+  textarea: true,
+  br: true,
+  img: true,
+  strong: true,
+  small: true,
+  code: true,
+  b: true,
+  big: true,
+  i: true,
+  tt: true,
+  abbr: true,
+  acronym: true,
+  cite: true,
+  dfn: true,
+  em: true,
+  kbd: true,
+  samp: true,
+  var: true,
+  bdo: true,
+  map: true,
+  object: true,
+  q: true,
+  script: true,
+  sub: true,
+  sup: true,
+}
+
+/**
+ * HTML void/self-closing elements that cannot have children. When Element
+ * detects one of these tags, it skips rendering beforeContent/content/afterContent
+ * and returns the Wrapper alone.
+ */
+export const EMPTY_ELEMENTS = {
+  area: true,
+  base: true,
+  br: true,
+  col: true,
+  embed: true,
+  hr: true,
+  img: true,
+  input: true,
+  keygen: true,
+  link: true,
+  textarea: true,
+  // 'meta': true,
+  // 'param': true,
+  source: true,
+  track: true,
+  wbr: true,
+}

package/src/Element/index.ts

@@ -0,0 +1,6 @@
+import component from "./component"
+import type { Props, PyreonElement } from "./types"
+
+export type { Props as ElementProps, PyreonElement }
+
+export { component as Element }

package/src/Element/types.ts

@@ -0,0 +1,168 @@
+import type { ComponentFn, PyreonHTMLAttributes } from "@pyreon/core"
+import type { HTMLTags } from "@pyreon/ui-core"
+import type {
+  AlignX,
+  AlignY,
+  Content,
+  Direction,
+  ExtendCss,
+  InnerRef,
+  PyreonStatic,
+  Responsive,
+  ResponsiveBoolType,
+} from "../types"
+
+export 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
+}> &
+  PyreonHTMLAttributes
+
+export type PyreonElement<P extends Record<string, unknown> = {}> = ComponentFn<Props & P> &
+  PyreonStatic

package/src/Element/utils.ts

@@ -0,0 +1,15 @@
+import { EMPTY_ELEMENTS, INLINE_ELEMENTS } from "./constants"
+
+type GetValue = (tag?: string) => boolean
+
+/** Checks whether the given HTML tag is an inline-level element, used to determine sub-tag nesting. */
+export const isInlineElement: GetValue = (tag) => {
+  if (tag && tag in INLINE_ELEMENTS) return true
+  return false
+}
+
+/** Checks whether the given HTML tag is a void element that cannot have children. */
+export const getShouldBeEmpty: GetValue = (tag) => {
+  if (tag && tag in EMPTY_ELEMENTS) return true
+  return false
+}

package/src/List/component.tsx

@@ -0,0 +1,57 @@
+/**
+ * List component that combines Iterator (data-driven rendering) with an
+ * optional Element root wrapper. When `rootElement` is false (default),
+ * it renders a bare Iterator as a fragment. When true, the Iterator output
+ * is wrapped in an Element that receives all non-iterator props (e.g.,
+ * layout, alignment, css), allowing the list to be styled as a single block.
+ */
+import { omit, pick } from "@pyreon/ui-core"
+import { PKG_NAME } from "../constants"
+import type { ElementProps, PyreonElement } from "../Element"
+import { Element } from "../Element"
+import type { Props as IteratorProps } from "../helpers/Iterator"
+import Iterator from "../helpers/Iterator"
+import type { MergeTypes } from "../types"
+
+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
+}
+
+export type Props = MergeTypes<[IteratorProps, ListProps]>
+
+const Component: PyreonElement<Props> = (({
+  rootElement = false,
+  ref,
+  ...props
+}: Partial<Props & ElementProps>) => {
+  const renderedList = <Iterator {...pick(props, Iterator.RESERVED_PROPS)} />
+
+  if (!rootElement) return renderedList
+
+  return (
+    <Element {...(ref ? { ref } : {})} {...omit(props, Iterator.RESERVED_PROPS)}>
+      {renderedList}
+    </Element>
+  )
+}) as PyreonElement<Props>
+
+const name = `${PKG_NAME}/List` as const
+
+Component.displayName = name
+Component.pkgName = PKG_NAME
+Component.PYREON__COMPONENT = name
+
+export default Component

package/src/List/index.ts

@@ -0,0 +1,5 @@
+import type { Props } from "./component"
+import component from "./component"
+
+export type { Props as ListProps }
+export { component as List }