@pyreon/coolgrid 0.11.0 → 0.11.2

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@pyreon/coolgrid",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "repository": {
     "type": "git",
-    "url": "https://github.com/pyreon/ui-system",
+    "url": "https://github.com/pyreon/pyreon",
     "directory": "packages/ui-system/coolgrid"
   },
   "description": "Responsive grid system for Pyreon",
@@ -11,10 +11,11 @@
   "type": "module",
   "sideEffects": false,
   "exports": {
-    "bun": "./src/index.ts",
-    "source": "./src/index.ts",
-    "import": "./lib/index.js",
-    "types": "./lib/index.d.ts"
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./lib/index.js",
+      "types": "./lib/index.d.ts"
+    }
   },
   "types": "./lib/index.d.ts",
   "main": "./lib/index.js",
@@ -23,7 +24,8 @@
     "!lib/**/*.map",
     "!lib/analysis",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "src"
   ],
   "engines": {
     "node": ">= 22"
@@ -42,14 +44,14 @@
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@pyreon/core": "^0.11.0",
-    "@pyreon/reactivity": "^0.11.0",
-    "@pyreon/ui-core": "^0.11.0",
-    "@pyreon/unistyle": "^0.11.0",
-    "@pyreon/styler": "^0.11.0"
+    "@pyreon/core": "^0.11.2",
+    "@pyreon/reactivity": "^0.11.2",
+    "@pyreon/ui-core": "^0.11.2",
+    "@pyreon/unistyle": "^0.11.2",
+    "@pyreon/styler": "^0.11.2"
   },
   "devDependencies": {
     "@vitus-labs/tools-rolldown": "^1.15.3",
-    "@pyreon/typescript": "^0.11.0"
+    "@pyreon/typescript": "^0.11.2"
   }
 }

package/src/Col/component.tsx

@@ -0,0 +1,61 @@
+import { useContext } from "@pyreon/core"
+import { PKG_NAME } from "../constants"
+import { RowContext } from "../context"
+import type { ElementType } from "../types"
+import useGridContext from "../useContext"
+import { omitCtxKeys } from "../utils"
+import Styled from "./styled"
+
+/**
+ * Col (column) component that reads grid settings from RowContext
+ * (columns, gap, gutter) and calculates its own width as a fraction
+ * of the total columns. Supports responsive size, padding, and visibility.
+ */
+
+const DEV_PROPS: Record<string, string> =
+  process.env.NODE_ENV !== "production" ? { "data-coolgrid": "col" } : {}
+
+const Component: ElementType<
+  [
+    "containerWidth",
+    "width",
+    "rowComponent",
+    "rowCss",
+    "colCss",
+    "colComponent",
+    "columns",
+    "gap",
+    "gutter",
+    "contentAlignX",
+  ]
+> = ({ children, component, css, ...props }) => {
+  const parentCtx = useContext(RowContext)
+  const { colCss, colComponent, columns, gap, size, padding } = useGridContext({
+    ...parentCtx,
+    ...props,
+  })
+
+  const finalProps = {
+    $coolgrid: {
+      columns,
+      gap,
+      size,
+      padding,
+      extraStyles: css ?? colCss,
+    },
+  }
+
+  return (
+    <Styled {...omitCtxKeys(props)} as={component ?? colComponent} {...finalProps} {...DEV_PROPS}>
+      {children}
+    </Styled>
+  )
+}
+
+const name = `${PKG_NAME}/Col`
+
+Component.displayName = name
+Component.pkgName = PKG_NAME
+Component.PYREON__COMPONENT = name
+
+export default Component

package/src/Col/index.ts

@@ -0,0 +1,3 @@
+import component from "./component"
+
+export default component

package/src/Col/styled.ts

@@ -0,0 +1,107 @@
+import { config } from "@pyreon/ui-core"
+import type { MakeItResponsiveStyles } from "@pyreon/unistyle"
+import { extendCss, makeItResponsive, value } from "@pyreon/unistyle"
+import type { CssOutput, StyledTypes } from "../types"
+import { hasValue, isNumber, isVisible } from "../utils"
+
+const { styled, css, component } = config
+
+type HasWidth = (size?: number, columns?: number) => boolean
+
+/** Returns true when both size and columns are valid, enabling explicit width calculation. */
+const hasWidth: HasWidth = (size, columns) => hasValue(size) && hasValue(columns)
+
+type WidthStyles = (
+  props: Pick<StyledTypes, "size" | "columns" | "gap">,
+  defaults: { rootSize?: number | undefined },
+) => CssOutput
+
+/**
+ * Calculates column width as a percentage of total columns, subtracting
+ * the gap when present. Uses `calc(%)` for web.
+ */
+const widthStyles: WidthStyles = ({ size, columns, gap }, { rootSize }) => {
+  if (!hasWidth(size, columns)) {
+    return ""
+  }
+
+  const s = size as number
+  const c = columns as number
+  const g = gap as number
+
+  // calculate % of width
+  const width = (s / c) * 100
+
+  const hasGap = hasValue(gap)
+
+  const val = hasGap ? `calc(${width}% - ${g}px)` : `${width}%`
+
+  const v = value(val, rootSize)
+
+  return css`
+    flex-grow: 0;
+    flex-shrink: 0;
+    max-width: ${v};
+    flex-basis: ${v};
+  `
+}
+
+type SpacingStyles = (type: "margin" | "padding", param?: number, rootSize?: number) => CssOutput
+/** Applies half of the given value as either margin or padding (used for gap and padding distribution). */
+const spacingStyles: SpacingStyles = (type, param, rootSize) => {
+  if (!isNumber(param)) {
+    return ""
+  }
+
+  const finalStyle = `${type}: ${value((param as number) / 2, rootSize)}`
+
+  return css`
+    ${finalStyle};
+  `
+}
+
+/**
+ * Main responsive style block for Col. When the column is visible, applies
+ * width, padding, margin, and extra CSS. When hidden (size === 0), moves
+ * the element off-screen with fixed positioning.
+ */
+const styles: MakeItResponsiveStyles<StyledTypes> = ({ theme, css: cssFn, rootSize }) => {
+  const { size, columns, gap, padding, extraStyles } = theme
+  const renderStyles = isVisible(size)
+
+  if (renderStyles) {
+    return cssFn`
+      left: initial;
+      position: relative;
+      ${widthStyles({ size, columns, gap }, { rootSize })};
+      ${spacingStyles("padding", padding, rootSize)};
+      ${spacingStyles("margin", gap, rootSize)};
+      ${extendCss(extraStyles)};
+    `
+  }
+
+  return cssFn`
+    left: -9999px;
+    position: fixed;
+    margin: 0;
+    padding: 0;
+  `
+}
+
+export default styled(component)`
+  box-sizing: border-box;
+  justify-content: stretch;
+
+  position: relative;
+  display: flex;
+  flex-basis: 0;
+  flex-grow: 1;
+  flex-direction: column;
+
+  ${makeItResponsive({
+    key: "$coolgrid",
+    styles,
+    css,
+    normalize: true,
+  })};
+`

package/src/Container/component.tsx

@@ -0,0 +1,82 @@
+import { provide } from "@pyreon/core"
+import { PKG_NAME } from "../constants"
+import ContainerContext from "../context/ContainerContext"
+import type { ElementType } from "../types"
+import useGridContext from "../useContext"
+import { omitCtxKeys } from "../utils"
+import Styled from "./styled"
+
+/**
+ * Container component that establishes the outermost grid boundary.
+ * Resolves grid config from the theme, provides it to descendant Row/Col
+ * components via ContainerContext, and renders a styled wrapper with
+ * responsive max-width.
+ */
+
+const DEV_PROPS: Record<string, string> =
+  process.env.NODE_ENV !== "production" ? { "data-coolgrid": "container" } : {}
+
+const Component: ElementType<["containerWidth"]> = ({
+  children,
+  component,
+  css,
+  width,
+  ...props
+}) => {
+  const {
+    containerWidth,
+    columns,
+    size,
+    gap,
+    padding,
+    gutter,
+    colCss,
+    colComponent,
+    rowCss,
+    rowComponent,
+    contentAlignX,
+  } = useGridContext(props)
+
+  const context = {
+    columns,
+    size,
+    gap,
+    padding,
+    gutter,
+    colCss,
+    colComponent,
+    rowCss,
+    rowComponent,
+    contentAlignX,
+  }
+
+  const finalWidth = (() => {
+    if (!width) return containerWidth
+    if (typeof width === "function") return width(containerWidth as Record<string, any>)
+    return width
+  })()
+
+  const finalProps = {
+    $coolgrid: {
+      width: finalWidth,
+      extraStyles: css,
+    },
+  }
+
+  // Provide container context to descendant Row/Col components
+  provide(ContainerContext, context)
+
+  return (
+    <Styled {...omitCtxKeys(props)} as={component} {...finalProps} {...DEV_PROPS}>
+      {children}
+    </Styled>
+  )
+}
+
+const name = `${PKG_NAME}/Container`
+
+Component.displayName = name
+Component.pkgName = PKG_NAME
+Component.PYREON__COMPONENT = name
+
+export default Component

package/src/Container/index.ts

@@ -0,0 +1,3 @@
+import component from "./component"
+
+export default component

package/src/Container/styled.ts

@@ -0,0 +1,37 @@
+import { config } from "@pyreon/ui-core"
+import type { MakeItResponsiveStyles } from "@pyreon/unistyle"
+import { extendCss, makeItResponsive, value } from "@pyreon/unistyle"
+import type { StyledTypes } from "../types"
+
+const { styled, css, component } = config
+
+/** Responsive styles that apply the container's max-width and any extra CSS at each breakpoint. */
+const styles: MakeItResponsiveStyles<Pick<StyledTypes, "width" | "extraStyles">> = ({
+  theme: t,
+  css: cssFn,
+  rootSize,
+}) => {
+  const w = t.width != null && typeof t.width !== "object" ? t.width : null
+
+  return cssFn`
+    ${w != null ? `max-width: ${value(w, rootSize)};` : ""};
+    ${extendCss(t.extraStyles)};
+  `
+}
+
+/** Styled Container element. Centered via auto margins with responsive max-width. */
+export default styled(component)`
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  width: 100%;
+  margin-right: auto;
+  margin-left: auto;
+
+  ${makeItResponsive({
+    key: "$coolgrid",
+    styles,
+    css,
+    normalize: true,
+  })};
+`

package/src/Container/utils.ts

@@ -0,0 +1,13 @@
+import { get } from "@pyreon/ui-core"
+
+/**
+ * Resolves the container max-width map using a three-layer fallback:
+ * props.width -> theme.grid.container -> theme.coolgrid.container.
+ */
+type GetContainerWidth = (
+  props?: Record<string, unknown> | unknown,
+  theme?: Record<string, unknown> | unknown,
+) => ReturnType<typeof get>
+
+export const getContainerWidth: GetContainerWidth = (props, theme) =>
+  get(props, "width") || get(theme, "grid.container") || get(theme, "coolgrid.container")

package/src/Row/component.tsx

@@ -0,0 +1,79 @@
+import { provide, useContext } from "@pyreon/core"
+import { PKG_NAME } from "../constants"
+import { ContainerContext, RowContext } from "../context"
+import type { ElementType } from "../types"
+import useGridContext from "../useContext"
+import { omitCtxKeys } from "../utils"
+import Styled from "./styled"
+
+/**
+ * Row component that reads inherited config from ContainerContext, merges
+ * it with its own props, and provides the resolved grid settings (columns,
+ * gap, gutter) to Col children via RowContext. Renders a flex-wrap container
+ * with negative margins to offset column gutters.
+ */
+
+const DEV_PROPS: Record<string, string> =
+  process.env.NODE_ENV !== "production" ? { "data-coolgrid": "row" } : {}
+
+const Component: ElementType<["containerWidth", "width", "rowComponent", "rowCss"]> = ({
+  children,
+  component,
+  css,
+  contentAlignX: rowAlignX,
+  ...props
+}) => {
+  const parentCtx = useContext(ContainerContext)
+
+  const {
+    columns,
+    gap,
+    gutter,
+    rowComponent,
+    rowCss,
+    contentAlignX,
+    containerWidth,
+    size,
+    padding,
+    colCss,
+    colComponent,
+  } = useGridContext({ ...parentCtx, ...props })
+
+  const context = {
+    containerWidth,
+    size,
+    padding,
+    colCss,
+    colComponent,
+    columns,
+    gap,
+    gutter,
+  }
+
+  const finalProps = {
+    $coolgrid: {
+      contentAlignX: rowAlignX || contentAlignX,
+      columns,
+      gap,
+      gutter,
+      extraStyles: css || rowCss,
+    },
+  }
+
+  // Provide row context to Col children
+  provide(RowContext, context)
+
+  return (
+    <Styled {...omitCtxKeys(props)} as={component || rowComponent} {...finalProps} {...DEV_PROPS}>
+      {children}
+    </Styled>
+  )
+}
+
+const name = `${PKG_NAME}/Row`
+
+Component.displayName = name
+Component.pkgName = PKG_NAME
+Component.PYREON__COMPONENT = name
+
+export default Component

package/src/Row/index.ts

@@ -0,0 +1,3 @@
+import component from "./component"
+
+export default component

package/src/Row/styled.ts

@@ -0,0 +1,70 @@
+import { config } from "@pyreon/ui-core"
+import type { MakeItResponsiveStyles } from "@pyreon/unistyle"
+import { ALIGN_CONTENT_MAP_X, extendCss, makeItResponsive, value } from "@pyreon/unistyle"
+import type { CssOutput, StyledTypes } from "../types"
+import { isNumber } from "../utils"
+
+const { styled, css, component } = config
+
+/**
+ * Computes negative horizontal margins to compensate for column gap,
+ * and vertical margins that account for gutter (inter-row spacing).
+ * This creates the classic grid pattern where column gaps cancel out
+ * at the row edges.
+ */
+type SpacingStyles = (
+  props: Pick<StyledTypes, "gap" | "gutter">,
+  { rootSize }: { rootSize?: number | undefined },
+) => CssOutput
+
+const spacingStyles: SpacingStyles = ({ gap, gutter }, { rootSize }) => {
+  if (!isNumber(gap)) return ""
+
+  const g = gap as number
+  const getValue = (param: string | number | null | undefined) => value(param, rootSize)
+
+  const spacingX = (g / 2) * -1
+  const spacingY = isNumber(gutter) ? (gutter as number) - g / 2 : g / 2
+
+  return css`
+    margin: ${getValue(spacingY)} ${getValue(spacingX)};
+  `
+}
+
+/** Maps the contentAlignX prop to a CSS justify-content value. */
+const contentAlign = (align?: StyledTypes["contentAlignX"]) => {
+  if (!align) return ""
+
+  return css`
+    justify-content: ${ALIGN_CONTENT_MAP_X[align]};
+  `
+}
+
+/** Composes spacing, alignment, and extra CSS into a single responsive style block for the Row. */
+const styles: MakeItResponsiveStyles<
+  Pick<StyledTypes, "gap" | "gutter" | "contentAlignX" | "extraStyles">
+> = ({ theme, css: cssFn, rootSize }) => {
+  const { gap, gutter, contentAlignX, extraStyles } = theme
+
+  return cssFn`
+    ${spacingStyles({ gap, gutter }, { rootSize })};
+    ${contentAlign(contentAlignX)};
+    ${extendCss(extraStyles)};
+  `
+}
+
+export default styled(component)`
+  box-sizing: border-box;
+
+  display: flex;
+  flex-wrap: wrap;
+  align-self: stretch;
+  flex-direction: row;
+
+  ${makeItResponsive({
+    key: "$coolgrid",
+    styles,
+    css,
+    normalize: true,
+  })};
+`

package/src/__tests__/Col.test.ts

@@ -0,0 +1,131 @@
+import type { VNode } from "@pyreon/core"
+import { beforeEach, describe, expect, it, vi } from "vitest"
+
+const mockProvide = vi.fn()
+const mockUseContext = vi.fn()
+
+vi.mock("@pyreon/core", async (importOriginal) => {
+  const original = await importOriginal<typeof import("@pyreon/core")>()
+  return {
+    ...original,
+    provide: (...args: any[]) => {
+      mockProvide(...args)
+    },
+    useContext: (ctx: any) => {
+      if (mockUseContext.mock.results.length > 0 || mockUseContext.mock.calls.length > 0) {
+        return mockUseContext(ctx)
+      }
+      return original.useContext(ctx)
+    },
+  }
+})
+
+// Mock unistyle context to return empty theme
+vi.mock("@pyreon/unistyle", async (importOriginal) => {
+  const original = await importOriginal<typeof import("@pyreon/unistyle")>()
+  return {
+    ...original,
+  }
+})
+
+const asVNode = (v: unknown) => v as VNode
+
+describe("Col", () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    // Default: no context (empty object)
+    mockUseContext.mockReturnValue({})
+  })
+
+  it("returns a VNode", async () => {
+    const Col = (await import("../Col")).default
+    const result = asVNode(Col({ children: "test" }))
+    expect(result).toBeDefined()
+    expect(result.type).toBeDefined()
+  })
+
+  it("has correct displayName", async () => {
+    const Col = (await import("../Col")).default
+    expect(Col.displayName).toBe("@pyreon/coolgrid/Col")
+  })
+
+  it("has correct pkgName", async () => {
+    const Col = (await import("../Col")).default
+    expect(Col.pkgName).toBe("@pyreon/coolgrid")
+  })
+
+  it("has PYREON__COMPONENT static", async () => {
+    const Col = (await import("../Col")).default
+    expect(Col.PYREON__COMPONENT).toBe("@pyreon/coolgrid/Col")
+  })
+
+  it("passes $coolgrid prop with grid values", async () => {
+    const Col = (await import("../Col")).default
+    const result = asVNode(Col({ size: 6, children: "test" }))
+    expect(result.props).toHaveProperty("$coolgrid")
+  })
+
+  it("does not provide context (Col only reads, never provides)", async () => {
+    const Col = (await import("../Col")).default
+    Col({ children: "test" })
+    expect(mockProvide).not.toHaveBeenCalled()
+  })
+
+  it("strips context keys from DOM props", async () => {
+    const Col = (await import("../Col")).default
+    const result = asVNode(
+      Col({
+        columns: 12,
+        gap: 16,
+        size: 6,
+        "data-testid": "my-col",
+        children: "test",
+      }),
+    )
+    // context keys should be stripped from the rendered props
+    // but $coolgrid should be present
+    expect(result.props.$coolgrid).toBeDefined()
+    expect(result.props["data-testid"]).toBe("my-col")
+  })
+
+  it("passes css as extraStyles when provided", async () => {
+    const Col = (await import("../Col")).default
+    const customCss = "background: green;"
+    const result = asVNode(Col({ css: customCss, children: "test" }))
+    expect((result.props.$coolgrid as Record<string, unknown>).extraStyles).toBe(customCss)
+  })
+
+  it("includes columns and gap in $coolgrid", async () => {
+    const Col = (await import("../Col")).default
+    const result = asVNode(Col({ columns: 12, gap: 16, size: 6, children: "test" }))
+    const coolgrid = result.props.$coolgrid as Record<string, unknown>
+    expect(coolgrid.columns).toBe(12)
+    expect(coolgrid.gap).toBe(16)
+    expect(coolgrid.size).toBe(6)
+  })
+
+  it("renders with data-coolgrid attribute in dev mode", async () => {
+    const Col = (await import("../Col")).default
+    const result = asVNode(Col({ children: "test" }))
+    expect(result.props["data-coolgrid"]).toBe("col")
+  })
+
+  it("passes component prop as 'as'", async () => {
+    const Col = (await import("../Col")).default
+    const customComponent = (() => null) as any
+    const result = asVNode(Col({ component: customComponent, children: "test" }))
+    expect(result.props.as).toBe(customComponent)
+  })
+
+  it("includes padding in $coolgrid", async () => {
+    const Col = (await import("../Col")).default
+    const result = asVNode(Col({ padding: 8, children: "test" }))
+    expect((result.props.$coolgrid as Record<string, unknown>).padding).toBe(8)
+  })
+
+  it("renders children in VNode", async () => {
+    const Col = (await import("../Col")).default
+    const result = asVNode(Col({ children: "hello" }))
+    expect(result.children).toBeDefined()
+  })
+})