@pyreon/coolgrid 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,214 @@
+# @pyreon/coolgrid
+
+Responsive grid system for Pyreon.
+
+Bootstrap-inspired Container / Row / Col grid with context-cascading configuration. Define breakpoints, column count, gaps, and gutters at any level — children inherit automatically. Every value is responsive.
+
+## Features
+
+- **Familiar mental model** — Container, Row, Col just like Bootstrap
+- **Context cascading** — set columns, gaps, and gutters at Container level, inherited by all Rows and Cols
+- **Responsive values** — single value, mobile-first array, or breakpoint object on every prop
+- **Custom breakpoints** — name and size them however you want
+- **Custom column counts** — 12, 24, 5 — any number
+- **Custom components** — swap Container, Row, or Col underlying elements
+- **Default Bootstrap theme** — included and ready to use
+
+## Installation
+
+```bash
+bun add @pyreon/coolgrid
+```
+
+## Quick Start
+
+```ts
+import { Container, Row, Col, Provider, theme } from '@pyreon/coolgrid'
+
+Provider({
+  theme,
+  children: Container({
+    children: Row({
+      children: [
+        Col({ size: 8, children: 'Main content' }),
+        Col({ size: 4, children: 'Sidebar' }),
+      ],
+    }),
+  }),
+})
+```
+
+## Components
+
+### Container
+
+Outermost grid boundary. Sets max-width and provides configuration context to descendants.
+
+```ts
+Container({
+  columns: 12,
+  gap: 16,
+  gutter: 24,
+  padding: 16,
+  children: Row({ children: '...' }),
+})
+```
+
+| Prop | Type | Description |
+| ---- | ---- | ----------- |
+| columns | `number` | Number of grid columns (default: 12) |
+| gap | `number` | Space between columns |
+| gutter | `number` | Outer gutter (negative margin offset on Row) |
+| padding | `number` | Column inner padding |
+| width | `value \| function` | Override container max-width |
+| component | `ComponentFn` | Custom root element |
+| css | `ExtendCss` | Extend container styling |
+| contentAlignX | `AlignX` | Horizontal alignment of columns |
+
+All configuration props cascade to Row and Col through context.
+
+### Row
+
+Flex wrapper with column management. Inherits Container config and can override it.
+
+```ts
+Row({
+  size: { xs: 12, md: 6 },
+  contentAlignX: 'center',
+  children: [
+    Col({ children: 'Column 1' }),
+    Col({ children: 'Column 2' }),
+  ],
+})
+```
+
+Setting `size` on Row applies it to all Cols inside:
+
+```ts
+// All columns are 6 of 12
+Row({
+  size: 6,
+  children: [
+    Col({ children: 'Half' }),
+    Col({ children: 'Half' }),
+  ],
+})
+```
+
+| Prop | Type | Description |
+| ---- | ---- | ----------- |
+| size | `number` | Default column size for all Cols inside |
+| component | `ComponentFn` | Custom row element |
+| css | `ExtendCss` | Extend row styling |
+| contentAlignX | `AlignX` | Override horizontal alignment |
+
+### Col
+
+Individual column. Width is calculated as a fraction of total columns.
+
+```ts
+// Fixed size
+Col({ size: 4, children: '1/3 width' })
+
+// Responsive size
+Col({ size: { xs: 12, sm: 6, lg: 4 }, children: 'Responsive' })
+
+// Hidden on mobile
+Col({ size: { xs: 0, md: 6 }, children: 'Hidden on xs' })
+```
+
+| Prop | Type | Description |
+| ---- | ---- | ----------- |
+| size | `number` | Column span (e.g. 4 of 12) |
+| padding | `number` | Override column inner padding |
+| component | `ComponentFn` | Custom column element |
+| css | `ExtendCss` | Extend column styling |
+
+## Configuration
+
+### Custom Breakpoints
+
+```ts
+Provider({
+  theme: {
+    rootSize: 16,
+    breakpoints: {
+      phone: 0,
+      tablet: 600,
+      desktop: 1024,
+      wide: 1440,
+    },
+  },
+  children: [/* ... */],
+})
+```
+
+### Custom Column Count
+
+```ts
+Container({
+  columns: 24,
+  children: Row({
+    children: [
+      Col({ size: 16, children: 'Two thirds' }),
+      Col({ size: 8, children: 'One third' }),
+    ],
+  }),
+})
+```
+
+### Context Cascading
+
+Configuration flows from Container through Row to Col via Pyreon's context system (`pushContext`/`popContext`):
+
+```text
+Container (columns: 12, gap: 16)
+  └─ Row (inherits columns, gap)
+       └─ Col (inherits columns, gap, calculates width)
+```
+
+Props set on a child override the inherited value for that level and below.
+
+## Default Theme
+
+The included `theme` export provides Bootstrap 4 defaults:
+
+```ts
+{
+  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 },
+  },
+}
+```
+
+## Responsive Values
+
+All numeric props support three formats:
+
+```ts
+// Single value
+Col({ size: 6 })
+
+// Array (mobile-first, by breakpoint position)
+Col({ size: [12, 6, 4] })
+
+// Object (explicit breakpoints)
+Col({ size: { xs: 12, md: 6, lg: 4 } })
+```
+
+## 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 |
+| @pyreon/styler | >= 0.0.1 |
+
+## License
+
+MIT

package/lib/index.d.ts

@@ -0,0 +1,75 @@
+import { Provider, extendCss } from "@pyreon/unistyle";
+import { ComponentFn, VNodeChild } from "@pyreon/core";
+import { BreakpointKeys, config } from "@pyreon/ui-core";
+
+//#region src/types.d.ts
+type CreateValueType<T> = T | T[] | Partial<Record<BreakpointKeys, T>>;
+type Value = string | number;
+type Css = Parameters<typeof extendCss>[0];
+type ExtraStyles = CreateValueType<Css>;
+type ValueType = CreateValueType<number>;
+type ContainerWidth = CreateValueType<Value>;
+type ContentAlignX = "center" | "left" | "right" | "spaceAround" | "spaceBetween" | "spaceEvenly";
+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);
+}>;
+type ComponentProps = ConfigurationProps & Partial<{
+  component: ComponentFn<any>;
+  css: ExtraStyles;
+}>;
+type ElementType<O extends string[]> = ComponentFn<Omit<ComponentProps, O[number]> & Record<string, unknown> & {
+  children?: VNodeChild;
+}> & {
+  displayName: string;
+  pkgName: string;
+  PYREON__COMPONENT: string;
+};
+//#endregion
+//#region src/Col/component.d.ts
+declare const Component: ElementType<["containerWidth", "width", "rowComponent", "rowCss", "colCss", "colComponent", "columns", "gap", "gutter", "contentAlignX"]>;
+//#endregion
+//#region src/Container/component.d.ts
+declare const Component$1: ElementType<["containerWidth"]>;
+//#endregion
+//#region src/Row/component.d.ts
+declare const Component$2: ElementType<["containerWidth", "width", "rowComponent", "rowCss"]>;
+//#endregion
+//#region src/theme.d.ts
+/**
+ * Default Bootstrap-like grid configuration. Provides 5 breakpoints (xs-xl),
+ * a 12-column grid, and responsive container max-widths matching Bootstrap 4.
+ */
+declare const _default: {
+  readonly rootSize: 16;
+  readonly breakpoints: {
+    readonly xs: 0;
+    readonly sm: 576;
+    readonly md: 768;
+    readonly lg: 992;
+    readonly xl: 1200;
+  };
+  readonly grid: {
+    readonly columns: 12;
+    readonly container: {
+      readonly xs: "100%";
+      readonly sm: 540;
+      readonly md: 720;
+      readonly lg: 960;
+      readonly xl: 1140;
+    };
+  };
+};
+//#endregion
+export { Component as Col, Component$1 as Container, Provider, Component$2 as Row, _default as theme };
+//# sourceMappingURL=index2.d.ts.map

package/lib/index.js

@@ -0,0 +1,387 @@
+import { ALIGN_CONTENT_MAP_X, Provider, context, extendCss, makeItResponsive, value } from "@pyreon/unistyle";
+import { createContext, onUnmount, popContext, pushContext, useContext } from "@pyreon/core";
+import { config, get, omit, pick } from "@pyreon/ui-core";
+import { jsx } from "@pyreon/core/jsx-runtime";
+
+//#region src/constants.ts
+const PKG_NAME = "@pyreon/coolgrid";
+/**
+* Grid configuration keys that are passed through context
+* from Container to Row and from Row to Col components.
+*/
+const CONTEXT_KEYS = [
+	"columns",
+	"size",
+	"gap",
+	"padding",
+	"gutter",
+	"colCss",
+	"colComponent",
+	"rowCss",
+	"rowComponent",
+	"contentAlignX"
+];
+
+//#endregion
+//#region src/context/ContainerContext.ts
+/**
+* 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.
+*/
+var ContainerContext_default = createContext({});
+
+//#endregion
+//#region src/context/RowContext.ts
+/**
+* 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.
+*/
+var RowContext_default = createContext({});
+
+//#endregion
+//#region src/useContext.tsx
+const pickThemeProps = (props, keywords) => pick(props, keywords);
+const getGridContext = (props = {}, theme = {}) => ({
+	columns: get(props, "columns") || get(theme, "grid.columns") || get(theme, "coolgrid.columns"),
+	containerWidth: get(props, "width") || get(theme, "grid.container") || get(theme, "coolgrid.container")
+});
+const useGridContext = (props) => {
+	const { theme } = useContext(context);
+	const ctxProps = pickThemeProps(props, CONTEXT_KEYS);
+	return {
+		...getGridContext(ctxProps, theme),
+		...ctxProps
+	};
+};
+
+//#endregion
+//#region src/utils.ts
+/** Checks whether a value is a finite number. */
+const isNumber = (value) => Number.isFinite(value);
+/** Checks whether a value is a finite number greater than zero. */
+const hasValue = (value) => 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.
+*/
+const isVisible = (value) => isNumber(value) && value !== 0 || value === void 0;
+const omitCtxKeys = (props) => omit(props, CONTEXT_KEYS);
+
+//#endregion
+//#region src/Col/styled.ts
+const { styled: styled$2, css: css$2, component: component$2 } = config;
+/** Returns true when both size and columns are valid, enabling explicit width calculation. */
+const hasWidth = (size, columns) => hasValue(size) && hasValue(columns);
+/**
+* Calculates column width as a percentage of total columns, subtracting
+* the gap when present. Uses `calc(%)` for web.
+*/
+const widthStyles = ({ size, columns, gap }, { rootSize }) => {
+	if (!hasWidth(size, columns)) return "";
+	const s = size;
+	const c = columns;
+	const g = gap;
+	const width = s / c * 100;
+	const v = value(hasValue(gap) ? `calc(${width}% - ${g}px)` : `${width}%`, rootSize);
+	return css$2`
+    flex-grow: 0;
+    flex-shrink: 0;
+    max-width: ${v};
+    flex-basis: ${v};
+  `;
+};
+/** Applies half of the given value as either margin or padding (used for gap and padding distribution). */
+const spacingStyles$1 = (type, param, rootSize) => {
+	if (!isNumber(param)) return "";
+	return css$2`
+    ${`${type}: ${value(param / 2, rootSize)}`};
+  `;
+};
+/**
+* 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$2 = ({ theme, css: cssFn, rootSize }) => {
+	const { size, columns, gap, padding, extraStyles } = theme;
+	if (isVisible(size)) return cssFn`
+      left: initial;
+      position: relative;
+      ${widthStyles({
+		size,
+		columns,
+		gap
+	}, { rootSize })};
+      ${spacingStyles$1("padding", padding, rootSize)};
+      ${spacingStyles$1("margin", gap, rootSize)};
+      ${extendCss(extraStyles)};
+    `;
+	return cssFn`
+    left: -9999px;
+    position: fixed;
+    margin: 0;
+    padding: 0;
+  `;
+};
+var styled_default$2 = styled$2(component$2)`
+  box-sizing: border-box;
+  justify-content: stretch;
+
+  position: relative;
+  display: flex;
+  flex-basis: 0;
+  flex-grow: 1;
+  flex-direction: column;
+
+  ${makeItResponsive({
+	key: "$coolgrid",
+	styles: styles$2,
+	css: css$2,
+	normalize: true
+})};
+`;
+
+//#endregion
+//#region src/Col/component.tsx
+/**
+* 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$2 = process.env.NODE_ENV !== "production" ? { "data-coolgrid": "col" } : {};
+const Component$2 = ({ children, component, css, ...props }) => {
+	const { colCss, colComponent, columns, gap, size, padding } = useGridContext({
+		...useContext(RowContext_default),
+		...props
+	});
+	const finalProps = { $coolgrid: {
+		columns,
+		gap,
+		size,
+		padding,
+		extraStyles: css ?? colCss
+	} };
+	return /* @__PURE__ */ jsx(styled_default$2, {
+		...omitCtxKeys(props),
+		as: component ?? colComponent,
+		...finalProps,
+		...DEV_PROPS$2,
+		children
+	});
+};
+const name$2 = `${PKG_NAME}/Col`;
+Component$2.displayName = name$2;
+Component$2.pkgName = PKG_NAME;
+Component$2.PYREON__COMPONENT = name$2;
+
+//#endregion
+//#region src/Col/index.ts
+var Col_default = Component$2;
+
+//#endregion
+//#region src/Container/styled.ts
+const { styled: styled$1, css: css$1, component: component$1 } = config;
+/** Responsive styles that apply the container's max-width and any extra CSS at each breakpoint. */
+const styles$1 = ({ 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. */
+var styled_default$1 = styled$1(component$1)`
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  width: 100%;
+  margin-right: auto;
+  margin-left: auto;
+
+  ${makeItResponsive({
+	key: "$coolgrid",
+	styles: styles$1,
+	css: css$1,
+	normalize: true
+})};
+`;
+
+//#endregion
+//#region src/Container/component.tsx
+/**
+* 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$1 = process.env.NODE_ENV !== "production" ? { "data-coolgrid": "container" } : {};
+const Component$1 = ({ 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 finalProps = { $coolgrid: {
+		width: (() => {
+			if (!width) return containerWidth;
+			if (typeof width === "function") return width(containerWidth);
+			return width;
+		})(),
+		extraStyles: css
+	} };
+	pushContext(new Map([[ContainerContext_default.id, context]]));
+	onUnmount(() => popContext());
+	return /* @__PURE__ */ jsx(styled_default$1, {
+		...omitCtxKeys(props),
+		as: component,
+		...finalProps,
+		...DEV_PROPS$1,
+		children
+	});
+};
+const name$1 = `${PKG_NAME}/Container`;
+Component$1.displayName = name$1;
+Component$1.pkgName = PKG_NAME;
+Component$1.PYREON__COMPONENT = name$1;
+
+//#endregion
+//#region src/Container/index.ts
+var Container_default = Component$1;
+
+//#endregion
+//#region src/Row/styled.ts
+const { styled, css, component } = config;
+const spacingStyles = ({ gap, gutter }, { rootSize }) => {
+	if (!isNumber(gap)) return "";
+	const g = gap;
+	const getValue = (param) => value(param, rootSize);
+	const spacingX = g / 2 * -1;
+	return css`
+    margin: ${getValue(isNumber(gutter) ? gutter - g / 2 : g / 2)} ${getValue(spacingX)};
+  `;
+};
+/** Maps the contentAlignX prop to a CSS justify-content value. */
+const contentAlign = (align) => {
+	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 = ({ theme, css: cssFn, rootSize }) => {
+	const { gap, gutter, contentAlignX, extraStyles } = theme;
+	return cssFn`
+    ${spacingStyles({
+		gap,
+		gutter
+	}, { rootSize })};
+    ${contentAlign(contentAlignX)};
+    ${extendCss(extraStyles)};
+  `;
+};
+var styled_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
+})};
+`;
+
+//#endregion
+//#region src/Row/component.tsx
+/**
+* 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 = process.env.NODE_ENV !== "production" ? { "data-coolgrid": "row" } : {};
+const Component = ({ children, component, css, contentAlignX: rowAlignX, ...props }) => {
+	const { columns, gap, gutter, rowComponent, rowCss, contentAlignX, containerWidth, size, padding, colCss, colComponent } = useGridContext({
+		...useContext(ContainerContext_default),
+		...props
+	});
+	const context = {
+		containerWidth,
+		size,
+		padding,
+		colCss,
+		colComponent,
+		columns,
+		gap,
+		gutter
+	};
+	const finalProps = { $coolgrid: {
+		contentAlignX: rowAlignX || contentAlignX,
+		columns,
+		gap,
+		gutter,
+		extraStyles: css || rowCss
+	} };
+	pushContext(new Map([[RowContext_default.id, context]]));
+	onUnmount(() => popContext());
+	return /* @__PURE__ */ jsx(styled_default, {
+		...omitCtxKeys(props),
+		as: component || rowComponent,
+		...finalProps,
+		...DEV_PROPS,
+		children
+	});
+};
+const name = `${PKG_NAME}/Row`;
+Component.displayName = name;
+Component.pkgName = PKG_NAME;
+Component.PYREON__COMPONENT = name;
+
+//#endregion
+//#region src/Row/index.ts
+var Row_default = Component;
+
+//#endregion
+//#region src/theme.ts
+/**
+* Default Bootstrap-like grid configuration. Provides 5 breakpoints (xs-xl),
+* a 12-column grid, and responsive container max-widths matching Bootstrap 4.
+*/
+var theme_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
+		}
+	}
+};
+
+//#endregion
+export { Col_default as Col, Container_default as Container, Provider, Row_default as Row, theme_default as theme };
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@pyreon/coolgrid",
+  "version": "0.0.2",
+  "description": "Responsive grid system for Pyreon",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "source": "./src/index.ts",
+    "import": "./lib/index.js",
+    "types": "./lib/index.d.ts"
+  },
+  "types": "./lib/index.d.ts",
+  "main": "./lib/index.js",
+  "files": [
+    "lib",
+    "!lib/**/*.map",
+    "!lib/analysis",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">= 18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepublish": "bun run build",
+    "build": "bun run vl_rolldown_build",
+    "build:watch": "bun run vl_rolldown_build-watch",
+    "lint": "biome check src/",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@pyreon/core": ">=0.3.0",
+    "@pyreon/reactivity": ">=0.3.0",
+    "@pyreon/ui-core": "^0.0.2",
+    "@pyreon/unistyle": "^0.0.2",
+    "@pyreon/styler": "^0.0.2"
+  },
+  "devDependencies": {
+    "@vitus-labs/tools-rolldown": "^1.15.0",
+    "@vitus-labs/tools-typescript": "^1.15.0"
+  }
+}