@pyreon/coolgrid 0.11.0 → 0.11.2

package/src/__tests__/utils.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest"
+import { getContainerWidth } from "../Container/utils"
+import { hasValue, hasWidth, isNumber, isVisible, omitCtxKeys } from "../utils"
+
+describe("isNumber", () => {
+  it("returns true for finite numbers", () => {
+    expect(isNumber(0)).toBe(true)
+    expect(isNumber(1)).toBe(true)
+    expect(isNumber(-1)).toBe(true)
+    expect(isNumber(3.14)).toBe(true)
+  })
+
+  it("returns false for non-finite values", () => {
+    expect(isNumber(Infinity)).toBe(false)
+    expect(isNumber(-Infinity)).toBe(false)
+    expect(isNumber(NaN)).toBe(false)
+  })
+
+  it("returns false for non-number types", () => {
+    expect(isNumber(null)).toBe(false)
+    expect(isNumber(undefined)).toBe(false)
+    expect(isNumber("5")).toBe(false)
+    expect(isNumber(true)).toBe(false)
+  })
+})
+
+describe("hasValue", () => {
+  it("returns true for positive finite numbers", () => {
+    expect(hasValue(1)).toBe(true)
+    expect(hasValue(12)).toBe(true)
+    expect(hasValue(0.5)).toBe(true)
+  })
+
+  it("returns false for zero", () => {
+    expect(hasValue(0)).toBe(false)
+  })
+
+  it("returns false for negative numbers", () => {
+    expect(hasValue(-1)).toBe(false)
+  })
+
+  it("returns false for non-numbers", () => {
+    expect(hasValue(null)).toBe(false)
+    expect(hasValue(undefined)).toBe(false)
+    expect(hasValue("5")).toBe(false)
+  })
+})
+
+describe("isVisible", () => {
+  it("returns true for positive numbers", () => {
+    expect(isVisible(1)).toBe(true)
+    expect(isVisible(12)).toBe(true)
+  })
+
+  it("returns true for negative numbers", () => {
+    expect(isVisible(-1)).toBe(true)
+  })
+
+  it("returns false for zero", () => {
+    expect(isVisible(0)).toBe(false)
+  })
+
+  it("returns true for undefined (default visibility)", () => {
+    expect(isVisible(undefined)).toBe(true)
+  })
+
+  it("returns false for non-number truthy values", () => {
+    expect(isVisible("5")).toBe(false)
+    expect(isVisible(null)).toBe(false)
+  })
+})
+
+describe("hasWidth", () => {
+  it("returns true when both size and columns are positive numbers", () => {
+    expect(hasWidth(6, 12)).toBe(true)
+    expect(hasWidth(1, 1)).toBe(true)
+  })
+
+  it("returns false when size is 0", () => {
+    expect(hasWidth(0, 12)).toBe(false)
+  })
+
+  it("returns false when columns is 0", () => {
+    expect(hasWidth(6, 0)).toBe(false)
+  })
+
+  it("returns false when either is not a number", () => {
+    expect(hasWidth(null, 12)).toBe(false)
+    expect(hasWidth(6, null)).toBe(false)
+    expect(hasWidth(undefined, undefined)).toBe(false)
+  })
+})
+
+describe("omitCtxKeys", () => {
+  it("strips context keys from props", () => {
+    const props = {
+      columns: 12,
+      size: 6,
+      gap: 16,
+      padding: 4,
+      gutter: 8,
+      colCss: "color: red;",
+      colComponent: () => null,
+      rowCss: "color: blue;",
+      rowComponent: () => null,
+      contentAlignX: "center",
+      className: "my-class",
+      id: "my-id",
+    }
+    const result = omitCtxKeys(props)
+    expect(result).toEqual({
+      className: "my-class",
+      id: "my-id",
+    })
+  })
+
+  it("returns all props when no context keys present", () => {
+    const props = { className: "test", style: "color: red;" }
+    const result = omitCtxKeys(props)
+    expect(result).toEqual(props)
+  })
+})
+
+describe("getContainerWidth", () => {
+  it("returns width from props", () => {
+    const result = getContainerWidth({ width: { xs: 600 } }, {})
+    expect(result).toEqual({ xs: 600 })
+  })
+
+  it("falls back to theme.grid.container", () => {
+    const result = getContainerWidth({}, { grid: { container: { xs: "100%" } } })
+    expect(result).toEqual({ xs: "100%" })
+  })
+
+  it("falls back to theme.coolgrid.container", () => {
+    const result = getContainerWidth({}, { coolgrid: { container: { md: 720 } } })
+    expect(result).toEqual({ md: 720 })
+  })
+
+  it("returns undefined when nothing matches", () => {
+    const result = getContainerWidth({}, {})
+    expect(result).toBeFalsy()
+  })
+})

package/src/constants.ts

@@ -0,0 +1,20 @@
+export const PKG_NAME = "@pyreon/coolgrid"
+
+/**
+ * Grid configuration keys that are passed through context
+ * from Container to Row and from Row to Col components.
+ */
+export const CONTEXT_KEYS = [
+  // 'breakpoints',
+  // 'rootSize',
+  "columns",
+  "size",
+  "gap",
+  "padding",
+  "gutter",
+  "colCss",
+  "colComponent",
+  "rowCss",
+  "rowComponent",
+  "contentAlignX",
+]

package/src/context/ContainerContext.ts

@@ -0,0 +1,9 @@
+import { createContext } from "@pyreon/core"
+import type { Context as ContextType } from "../types"
+
+/**
+ * Context for container-level grid configuration.
+ * Provided by the Container component and consumed by Row children
+ * to inherit columns, gap, gutter, and other grid settings.
+ */
+export default createContext<ContextType>({})

package/src/context/RowContext.ts

@@ -0,0 +1,9 @@
+import { createContext } from "@pyreon/core"
+import type { Context as ContextType } from "../types"
+
+/**
+ * Context for row-level grid configuration.
+ * Provided by the Row component and consumed by Col children
+ * to inherit columns, gap, gutter, and sizing for width calculations.
+ */
+export default createContext<ContextType>({})

package/src/context/index.ts

@@ -0,0 +1,4 @@
+import ContainerContext from "./ContainerContext"
+import RowContext from "./RowContext"
+
+export { ContainerContext, RowContext }

package/src/index.ts

@@ -0,0 +1,7 @@
+import { Provider } from "@pyreon/unistyle"
+import Col from "./Col"
+import Container from "./Container"
+import Row from "./Row"
+import theme from "./theme"
+
+export { Col, Container, Provider, Row, theme }

package/src/theme.ts

@@ -0,0 +1,40 @@
+/**
+ * Default Bootstrap-like grid configuration. Provides 5 breakpoints (xs-xl),
+ * a 12-column grid, and responsive container max-widths matching Bootstrap 4.
+ */
+export default {
+  rootSize: 16,
+  breakpoints: {
+    xs: 0,
+    sm: 576,
+    md: 768,
+    lg: 992,
+    xl: 1200,
+  },
+  grid: {
+    columns: 12,
+    container: {
+      xs: "100%",
+      sm: 540,
+      md: 720,
+      lg: 960,
+      xl: 1140,
+    },
+  },
+} as const
+
+export const defaultBreakpoints: Record<string, number> = {
+  xs: 0,
+  sm: 576,
+  md: 768,
+  lg: 992,
+  xl: 1200,
+}
+
+export const defaultContainerWidths: Record<string, string | number> = {
+  xs: "100%",
+  sm: 540,
+  md: 720,
+  lg: 960,
+  xl: 1140,
+}

package/src/types.ts

@@ -0,0 +1,72 @@
+/**
+ * Type definitions for the coolgrid layout system.
+ * Supports responsive values as single values, arrays (mobile-first),
+ * or breakpoint-keyed objects. Defines config props for Container/Row/Col
+ * and the resolved styled-component prop types.
+ */
+
+import type { ComponentFn, VNodeChild } from "@pyreon/core"
+import type { BreakpointKeys, config } from "@pyreon/ui-core"
+import type { AlignContentAlignXKeys, extendCss } from "@pyreon/unistyle"
+
+type CreateValueType<T> = T | T[] | Partial<Record<BreakpointKeys, T>>
+
+export type Obj = Record<string, unknown>
+export type Value = string | number
+export type Css = Parameters<typeof extendCss>[0]
+export type ExtraStyles = CreateValueType<Css>
+
+export type CssOutput = ReturnType<typeof config.css> | string
+
+export type ValueType = CreateValueType<number>
+export type ContainerWidth = CreateValueType<Value>
+
+export type ContentAlignX =
+  | "center"
+  | "left"
+  | "right"
+  | "spaceAround"
+  | "spaceBetween"
+  | "spaceEvenly"
+
+export type ConfigurationProps = Partial<{
+  size: ValueType
+  padding: ValueType
+  gap: ValueType
+  gutter: ValueType
+  columns: ValueType
+  colCss: ExtraStyles
+  rowCss: ExtraStyles
+  colComponent: ComponentFn<any>
+  rowComponent: ComponentFn<any>
+  contentAlignX: ContentAlignX
+  containerWidth: ContainerWidth
+  width: ContainerWidth | ((widths: Record<string, any>) => ContainerWidth)
+}>
+
+export type ComponentProps = ConfigurationProps &
+  Partial<{
+    component: ComponentFn<any>
+    css: ExtraStyles
+  }>
+
+export type StyledTypes = Partial<{
+  size: number | undefined
+  padding: number | undefined
+  gap: number | undefined
+  gutter: number | undefined
+  columns: number | undefined
+  extraStyles: Css
+  contentAlignX: AlignContentAlignXKeys
+  width: Value
+}>
+
+export type ElementType<O extends string[]> = ComponentFn<
+  Omit<ComponentProps, O[number]> & Record<string, unknown> & { children?: VNodeChild }
+> & {
+  displayName: string
+  pkgName: string
+  PYREON__COMPONENT: string
+}
+
+export type Context = { [K in keyof ConfigurationProps]?: ConfigurationProps[K] | undefined }

package/src/useContext.tsx

@@ -0,0 +1,54 @@
+import { useContext } from "@pyreon/core"
+import { get, pick } from "@pyreon/ui-core"
+import { context } from "@pyreon/unistyle"
+import { CONTEXT_KEYS } from "./constants"
+import type { Context, Obj, ValueType } from "./types"
+
+/**
+ * Picks only the recognized grid configuration keys from a props object,
+ * filtering out any non-grid props before they enter context resolution.
+ */
+export type PickThemeProps = <T extends Record<string, unknown>>(
+  props: T,
+  keywords: Array<keyof T>,
+) => ReturnType<typeof pick>
+const pickThemeProps: PickThemeProps = (props, keywords) => pick(props, keywords)
+
+/**
+ * Resolves grid columns and container width using a three-layer fallback:
+ * 1. Explicit component props (e.g. `columns={6}`)
+ * 2. `theme.grid.columns` / `theme.grid.container`
+ * 3. `theme.coolgrid.columns` / `theme.coolgrid.container`
+ */
+type GetGridContext = (
+  props: Obj,
+  theme: Obj,
+) => {
+  columns?: ValueType
+  containerWidth?: Record<string, number>
+}
+
+export const getGridContext: GetGridContext = (props = {}, theme = {}) => ({
+  columns: (get(props, "columns") ||
+    get(theme, "grid.columns") ||
+    get(theme, "coolgrid.columns")) as ValueType,
+  containerWidth: (get(props, "width") ||
+    get(theme, "grid.container") ||
+    get(theme, "coolgrid.container")) as Record<string, number>,
+})
+
+/**
+ * Hook that reads the unistyle theme context and merges it with the
+ * component's own props to produce the final grid configuration.
+ * Applies the three-layer resolution (props -> grid.* -> coolgrid.*).
+ */
+type UseGridContext = (props: Obj) => Context
+const useGridContext: UseGridContext = (props) => {
+  const { theme } = useContext(context)
+  const ctxProps = pickThemeProps(props, CONTEXT_KEYS)
+  const gridContext = getGridContext(ctxProps, theme as Record<string, unknown>)
+
+  return { ...gridContext, ...ctxProps }
+}
+
+export default useGridContext

package/src/utils.ts

@@ -0,0 +1,23 @@
+import { omit } from "@pyreon/ui-core"
+import { CONTEXT_KEYS } from "./constants"
+
+/** Checks whether a value is a finite number. */
+export const isNumber = (value: unknown): value is number => Number.isFinite(value)
+
+/** Checks whether a value is a finite number greater than zero. */
+export const hasValue = (value: unknown): boolean => isNumber(value) && value > 0
+
+/**
+ * Determines if a column should be visible. A column is visible when its
+ * size is undefined (auto) or a non-zero number. Size 0 hides the column.
+ */
+export const isVisible = (value: unknown): boolean =>
+  (isNumber(value) && value !== 0) || value === undefined
+
+/** Returns true when both size and columns are positive numbers, indicating an explicit width can be calculated. */
+type HasWidth = (size: unknown, columns: unknown) => boolean
+export const hasWidth: HasWidth = (size, columns) => !!(hasValue(size) && hasValue(columns))
+
+/** Strips grid context keys from a props object so they are not forwarded to the DOM element. */
+type OmitCtxKeys = (props?: Record<string, any>) => ReturnType<typeof omit>
+export const omitCtxKeys: OmitCtxKeys = (props) => omit(props, CONTEXT_KEYS)