@pithyjs/ui-kit 0.1.0-beta.0

package/dist/layout/Grid.js

@@ -0,0 +1,272 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.grid",
+  "title": "<Grid> Layout Component",
+  "category": "feature"
+}
+*/
+import { renderChildren } from '@pithyjs/core';
+import { GAP_CLASS, ROW_GAP_CLASS, COL_GAP_CLASS, ALIGN_CLASS, JUSTIFY_CLASS, CSS_LENGTH_PATTERN, } from '../shared/common';
+import { GRID_COLS_CLASS, RESPONSIVE_GRID_COLS, GRID_ROWS_CLASS, } from '../shared/grid';
+import { CONTAINER_BREAKPOINT_NAMES, GRID_FLUID_MIN_COLUMN_WIDTH, SPACING_CSS_VAR, } from '@pithyjs/design-system';
+// ── Helpers ─────────────────────────────────────────────────────────────
+function clampCols(n) {
+    if (!Number.isFinite(n))
+        return 1;
+    return Math.max(1, Math.min(12, Math.round(n)));
+}
+/** Regex matching GridItem placement utility classes that require explicit grid tracks. */
+const PLACEMENT_RE = /\bu-(col-start|col-end|col-span|row-start|row-end|row-span)-/;
+/**
+ * Scans direct children of a fragment/element for GridItem placement classes.
+ * When children use explicit placement (span, start, end), the grid must use
+ * fixed column tracks — auto-fit would create implicit tracks that break
+ * those placements.
+ */
+function hasPlacementClasses(fragment) {
+    const children = fragment.children;
+    for (let i = 0; i < children.length; i++) {
+        const el = children[i];
+        for (let j = 0; j < el.classList.length; j++) {
+            if (PLACEMENT_RE.test(el.classList[j]))
+                return true;
+        }
+    }
+    return false;
+}
+function buildGapClasses(gap, rowGap, colGap) {
+    if (rowGap != null && colGap != null) {
+        return [ROW_GAP_CLASS[rowGap], COL_GAP_CLASS[colGap]];
+    }
+    if (rowGap != null) {
+        return [ROW_GAP_CLASS[rowGap], COL_GAP_CLASS[gap]];
+    }
+    if (colGap != null) {
+        return [ROW_GAP_CLASS[gap], COL_GAP_CLASS[colGap]];
+    }
+    return [GAP_CLASS[gap]];
+}
+/**
+ * Builds a fluid CSS grid-template-columns value that targets N columns at
+ * wide widths and gracefully collapses to fewer columns at narrow widths,
+ * using pure CSS — no breakpoints or container queries required.
+ *
+ * Uses design system spacing CSS variables for the gap calculation.
+ *
+ * Formula: repeat(auto-fit, minmax(min(100%, max(FLOOR, calc((100% - (N-1) * GAP_VAR) / N - 0.01px))), 1fr))
+ *
+ * - `calc(...)` computes the exact per-column width for N columns minus a tiny epsilon.
+ * - `max(FLOOR, ...)` sets the collapse threshold — when columns would be smaller than FLOOR, auto-fit reduces count.
+ * - `min(100%, ...)` ensures single-column works at very narrow widths.
+ */
+function buildFluidGridCols(cols, gapCssVar, minColumnWidth) {
+    const gapCount = cols - 1;
+    const floor = minColumnWidth ?? GRID_FLUID_MIN_COLUMN_WIDTH;
+    return `repeat(auto-fit, minmax(min(100%, max(${floor}, calc((100% - ${gapCount} * ${gapCssVar}) / ${cols} - 0.01px))), 1fr))`;
+}
+// ── Component ───────────────────────────────────────────────────────────
+/**
+ * Layout atom that arranges children in a CSS grid.
+ *
+ * Mobile-first: defaults to 1 column. Supports simple column counts (which
+ * are fluid-responsive by default), explicit responsive breakpoints via
+ * container queries, and intrinsic auto-fit/fill patterns.
+ *
+ * When `columns` is a number ≥ 2, the grid uses a fluid CSS formula that
+ * targets that exact column count at wide widths but gracefully collapses
+ * to fewer columns at narrow widths — no breakpoints required.
+ *
+ * @example
+ * ```html
+ * <!-- Fluid 3-column grid (collapses gracefully on mobile) -->
+ * <Grid columns="3" gap="'lg'">
+ *   <div>Cell 1</div>
+ *   <div>Cell 2</div>
+ *   <div>Cell 3</div>
+ * </Grid>
+ *
+ * <!-- Explicit responsive: 1 col mobile → 2 col tablet → 3 col desktop -->
+ * <Grid columns="{ base: 1, sm: 2, lg: 3 }">
+ *   <div>A</div>
+ *   <div>B</div>
+ *   <div>C</div>
+ * </Grid>
+ *
+ * <!-- Auto-fit with minimum 250px columns -->
+ * <Grid columns="'auto-fit'" minColumnWidth="'250px'">
+ *   <div>Card</div>
+ *   <div>Card</div>
+ *   <div>Card</div>
+ * </Grid>
+ * ```
+ */
+/** @codexApi {"parent":"pithy.ui-kit.grid","name":"Grid","stability":"stable","signature":"(props?: GridProps) => { el: HTMLElement | DocumentFragment; destroy: () => void }"} */
+export function Grid({ columns = 1, rows = undefined, gap: rawGap = 'md', rowGap: rawRowGap = undefined, colGap: rawColGap = undefined, align: rawAlign = undefined, justify: rawJustify = undefined, minColumnWidth = undefined, as = 'div', } = {}) {
+    // Validate and fall back unconditionally (not just DEV) to prevent undefined class names in production
+    const hasOwn = Object.prototype.hasOwnProperty;
+    const validGap = hasOwn.call(GAP_CLASS, rawGap);
+    const validRowGap = rawRowGap == null || hasOwn.call(ROW_GAP_CLASS, rawRowGap);
+    const validColGap = rawColGap == null || hasOwn.call(COL_GAP_CLASS, rawColGap);
+    const validAlign = rawAlign == null || hasOwn.call(ALIGN_CLASS, rawAlign);
+    const validJustify = rawJustify == null || hasOwn.call(JUSTIFY_CLASS, rawJustify);
+    if (import.meta.env?.DEV) {
+        if (!validGap) {
+            const valid = Object.keys(GAP_CLASS).join(', ');
+            console.warn(`[<Grid>] Invalid gap value: "${rawGap}". Expected one of: ${valid}. Falling back to "md".`);
+        }
+        if (!validRowGap) {
+            const valid = Object.keys(ROW_GAP_CLASS).join(', ');
+            console.warn(`[<Grid>] Invalid rowGap value: "${rawRowGap}". Expected one of: ${valid}. Ignoring.`);
+        }
+        if (!validColGap) {
+            const valid = Object.keys(COL_GAP_CLASS).join(', ');
+            console.warn(`[<Grid>] Invalid colGap value: "${rawColGap}". Expected one of: ${valid}. Ignoring.`);
+        }
+        if (!validAlign) {
+            const valid = Object.keys(ALIGN_CLASS).join(', ');
+            console.warn(`[<Grid>] Invalid align value: "${rawAlign}". Expected one of: ${valid}. Ignoring.`);
+        }
+        if (!validJustify) {
+            const valid = Object.keys(JUSTIFY_CLASS).join(', ');
+            console.warn(`[<Grid>] Invalid justify value: "${rawJustify}". Expected one of: ${valid}. Ignoring.`);
+        }
+        if (minColumnWidth != null && !CSS_LENGTH_PATTERN.test(minColumnWidth)) {
+            console.warn(`[<Grid>] Suspicious minColumnWidth value: "${minColumnWidth}". Expected a CSS length (e.g. "250px", "15rem"). Note: fr units are not valid inside minmax().`);
+        }
+    }
+    const gap = validGap ? rawGap : 'md';
+    const rowGap = validRowGap ? rawRowGap : undefined;
+    const colGap = validColGap ? rawColGap : undefined;
+    const align = validAlign ? rawAlign : undefined;
+    const justify = validJustify ? rawJustify : undefined;
+    const rowCount = rows != null && Number.isFinite(rows)
+        ? Math.max(1, Math.min(6, Math.round(rows)))
+        : undefined;
+    const gapClasses = buildGapClasses(gap, rowGap, colGap);
+    const alignClass = align ? ALIGN_CLASS[align] : '';
+    const justifyClass = justify ? JUSTIFY_CLASS[justify] : '';
+    const rowClass = rowCount != null ? GRID_ROWS_CLASS[rowCount] : '';
+    // Compile children through full pipeline (enables nested <GridItem>, <Stack>, etc.)
+    const { el: childFragment, destroy } = renderChildren();
+    // ── Auto-fit / auto-fill ──────────────────────────────────
+    if (columns === 'auto-fit' || columns === 'auto-fill') {
+        const autoClass = columns === 'auto-fit' ? 'u-grid-auto-fit' : 'u-grid-auto-fill';
+        const classes = [
+            'u-grid',
+            autoClass,
+            rowClass,
+            ...gapClasses,
+            alignClass,
+            justifyClass,
+        ].filter(Boolean);
+        const wrapper = document.createElement(as);
+        for (const cls of classes)
+            wrapper.classList.add(cls);
+        if (minColumnWidth)
+            wrapper.style.setProperty('--grid-auto-min', minColumnWidth);
+        wrapper.appendChild(childFragment);
+        return {
+            el: wrapper,
+            destroy: () => {
+                destroy();
+                wrapper.replaceChildren();
+            },
+        };
+    }
+    // ── Responsive object ─────────────────────────────────────
+    if (columns != null && typeof columns === 'object') {
+        const base = clampCols(columns.base ?? 1);
+        const bpClasses = CONTAINER_BREAKPOINT_NAMES.filter(bp => columns[bp] != null).map(bp => RESPONSIVE_GRID_COLS[bp][clampCols(columns[bp])]);
+        const gridClasses = [
+            'u-grid',
+            GRID_COLS_CLASS[base],
+            ...bpClasses,
+            rowClass,
+            ...gapClasses,
+            alignClass,
+            justifyClass,
+        ].filter(Boolean);
+        const outer = document.createElement('div');
+        outer.classList.add('u-container-inline');
+        const inner = document.createElement(as);
+        for (const cls of gridClasses)
+            inner.classList.add(cls);
+        inner.appendChild(childFragment);
+        outer.appendChild(inner);
+        return {
+            el: outer,
+            destroy: () => {
+                destroy();
+                inner.replaceChildren();
+                outer.replaceChildren();
+            },
+        };
+    }
+    // ── Simple number ─────────────────────────────────────────
+    const cols = clampCols(columns);
+    // For 2+ columns: use fluid CSS formula unless rows is set or children
+    // use explicit GridItem placement (span, start, end) which requires
+    // fixed column tracks — auto-fit would create implicit tracks that
+    // break those placements.
+    if (cols >= 2 && rowCount == null && !hasPlacementClasses(childFragment)) {
+        const effectiveColGap = colGap ?? gap;
+        const gapCssVar = SPACING_CSS_VAR[effectiveColGap];
+        const classes = ['u-grid', ...gapClasses, alignClass, justifyClass].filter(Boolean);
+        const wrapper = document.createElement(as);
+        for (const cls of classes)
+            wrapper.classList.add(cls);
+        wrapper.style.gridTemplateColumns = buildFluidGridCols(cols, gapCssVar, minColumnWidth);
+        wrapper.appendChild(childFragment);
+        return {
+            el: wrapper,
+            destroy: () => {
+                destroy();
+                wrapper.replaceChildren();
+            },
+        };
+    }
+    // For 2+ columns with rows or explicit placement: use fixed column count
+    // to preserve GridItem placement (span, start, rowSpan).
+    if (cols >= 2) {
+        const classes = [
+            'u-grid',
+            GRID_COLS_CLASS[cols],
+            rowClass,
+            ...gapClasses,
+            alignClass,
+            justifyClass,
+        ].filter(Boolean);
+        const wrapper = document.createElement(as);
+        for (const cls of classes)
+            wrapper.classList.add(cls);
+        wrapper.appendChild(childFragment);
+        return {
+            el: wrapper,
+            destroy: () => {
+                destroy();
+                wrapper.replaceChildren();
+            },
+        };
+    }
+    // Single column — no fluid behavior needed
+    const classes = [
+        'u-grid',
+        GRID_COLS_CLASS[cols],
+        rowClass,
+        ...gapClasses,
+        alignClass,
+        justifyClass,
+    ].filter(Boolean);
+    const wrapper = document.createElement(as);
+    for (const cls of classes)
+        wrapper.classList.add(cls);
+    wrapper.appendChild(childFragment);
+    return {
+        el: wrapper,
+        destroy: () => {
+            destroy();
+            wrapper.replaceChildren();
+        },
+    };
+}
+//# sourceMappingURL=Grid.js.map

package/dist/layout/Grid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Grid.js","sourceRoot":"","sources":["../../src/layout/Grid.ts"],"names":[],"mappings":"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"}

package/dist/layout/GridItem.d.ts

@@ -0,0 +1,52 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.grid-item",
+  "title": "<GridItem> Layout Component",
+  "category": "feature"
+}
+*/
+import { type PlaceSelf } from '../shared/grid';
+/** @codexApi {"parent":"pithy.ui-kit.grid-item","name":"GridItemProps","stability":"stable","signature":"interface GridItemProps"} */
+export interface GridItemProps {
+    /** Column span (1-12 or "full") — maps to u-col-span-* */
+    span?: number | 'full';
+    /** Column start line (1-13) — maps to u-col-start-* */
+    start?: number;
+    /** Column end line (1-13) — maps to u-col-end-* */
+    end?: number;
+    /** Row span (1-6) — maps to u-row-span-* */
+    rowSpan?: number;
+    /** Row start line (1-7) — maps to u-row-start-* */
+    rowStart?: number;
+    /** Row end line (1-7) — maps to u-row-end-* */
+    rowEnd?: number;
+    /** Place self alignment — maps to u-place-self-* */
+    placeSelf?: PlaceSelf;
+    /** HTML tag to render (default: "div") */
+    as?: keyof HTMLElementTagNameMap;
+}
+/**
+ * Grid child component for structured placement within a Grid.
+ *
+ * Designed for use inside Grid — maps props to existing utility classes
+ * for column/row spanning and positioning. Critical for site builder
+ * serialization and property panels.
+ *
+ * @example
+ * ```html
+ * <Grid columns="3">
+ *   <GridItem span="2">
+ *     <div>Spans 2 columns</div>
+ *   </GridItem>
+ *   <GridItem start="3">
+ *     <div>Starts at column 3</div>
+ *   </GridItem>
+ * </Grid>
+ * ```
+ */
+/** @codexApi {"parent":"pithy.ui-kit.grid-item","name":"GridItem","stability":"stable","signature":"(props?: GridItemProps) => { el: HTMLElement | DocumentFragment; destroy: () => void }"} */
+export declare function GridItem({ span, start, end, rowSpan, rowStart, rowEnd, placeSelf, as, }?: GridItemProps): {
+    el: HTMLElement | DocumentFragment;
+    destroy: () => void;
+};
+//# sourceMappingURL=GridItem.d.ts.map

package/dist/layout/GridItem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GridItem.d.ts","sourceRoot":"","sources":["../../src/layout/GridItem.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAIF,OAAO,EASL,KAAK,SAAS,EACf,MAAM,gBAAgB,CAAC;AAOxB,sIAAsI;AACtI,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,0CAA0C;IAC1C,EAAE,CAAC,EAAE,MAAM,qBAAqB,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,gMAAgM;AAChM,wBAAgB,QAAQ,CAAC,EACvB,IAAgB,EAChB,KAAiB,EACjB,GAAe,EACf,OAAmB,EACnB,QAAoB,EACpB,MAAkB,EAClB,SAAqB,EACrB,EAAU,GACX,GAAE,aAAkB,GAAG;IACtB,EAAE,EAAE,WAAW,GAAG,gBAAgB,CAAC;IACnC,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAiEA"}

package/dist/layout/GridItem.js

@@ -0,0 +1,99 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.grid-item",
+  "title": "<GridItem> Layout Component",
+  "category": "feature"
+}
+*/
+import { renderChildren } from '@pithyjs/core';
+import { captureSlot } from '../shared/slots';
+import { COL_SPAN_CLASS, COL_START_CLASS, COL_END_CLASS, ROW_SPAN_CLASS, ROW_START_CLASS, ROW_END_CLASS, PLACE_SELF_CLASS, PLACE_SELF_ITEMS, } from '../shared/grid';
+function clampFinite(n, min, max) {
+    if (!Number.isFinite(n))
+        return undefined;
+    return Math.max(min, Math.min(max, Math.round(n)));
+}
+/**
+ * Grid child component for structured placement within a Grid.
+ *
+ * Designed for use inside Grid — maps props to existing utility classes
+ * for column/row spanning and positioning. Critical for site builder
+ * serialization and property panels.
+ *
+ * @example
+ * ```html
+ * <Grid columns="3">
+ *   <GridItem span="2">
+ *     <div>Spans 2 columns</div>
+ *   </GridItem>
+ *   <GridItem start="3">
+ *     <div>Starts at column 3</div>
+ *   </GridItem>
+ * </Grid>
+ * ```
+ */
+/** @codexApi {"parent":"pithy.ui-kit.grid-item","name":"GridItem","stability":"stable","signature":"(props?: GridItemProps) => { el: HTMLElement | DocumentFragment; destroy: () => void }"} */
+export function GridItem({ span = undefined, start = undefined, end = undefined, rowSpan = undefined, rowStart = undefined, rowEnd = undefined, placeSelf = undefined, as = 'div', } = {}) {
+    const classes = [];
+    // Column span
+    if (span === 'full') {
+        classes.push('u-col-span-full');
+    }
+    else if (span != null) {
+        const n = clampFinite(span, 1, 12);
+        if (n != null)
+            classes.push(COL_SPAN_CLASS[n]);
+    }
+    // Column start/end
+    if (start != null) {
+        const n = clampFinite(start, 1, 13);
+        if (n != null)
+            classes.push(COL_START_CLASS[n]);
+    }
+    if (end != null) {
+        const n = clampFinite(end, 1, 13);
+        if (n != null)
+            classes.push(COL_END_CLASS[n]);
+    }
+    // Row span
+    if (rowSpan != null) {
+        const n = clampFinite(rowSpan, 1, 6);
+        if (n != null)
+            classes.push(ROW_SPAN_CLASS[n]);
+    }
+    // Row start/end
+    if (rowStart != null) {
+        const n = clampFinite(rowStart, 1, 7);
+        if (n != null)
+            classes.push(ROW_START_CLASS[n]);
+    }
+    if (rowEnd != null) {
+        const n = clampFinite(rowEnd, 1, 7);
+        if (n != null)
+            classes.push(ROW_END_CLASS[n]);
+    }
+    // Place self — guard against invalid values to prevent "undefined" class name
+    if (placeSelf != null &&
+        PLACE_SELF_ITEMS.includes(placeSelf)) {
+        classes.push(PLACE_SELF_CLASS[placeSelf]);
+    }
+    else if (placeSelf != null && import.meta.env?.DEV) {
+        const valid = PLACE_SELF_ITEMS.join(', ');
+        console.warn(`[<GridItem>] Invalid placeSelf value: "${placeSelf}". Expected one of: ${valid}. Ignoring.`);
+    }
+    // Compile children through full pipeline
+    const { el: childFragment, destroy } = renderChildren();
+    const wrapper = document.createElement(as);
+    for (const cls of classes)
+        wrapper.classList.add(cls);
+    captureSlot(wrapper, 'default');
+    wrapper.appendChild(childFragment);
+    return {
+        el: wrapper,
+        destroy: () => {
+            destroy();
+            wrapper.replaceChildren();
+        },
+    };
+}
+//# sourceMappingURL=GridItem.js.map

package/dist/layout/GridItem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GridItem.js","sourceRoot":"","sources":["../../src/layout/GridItem.ts"],"names":[],"mappings":"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"}

package/dist/layout/PageSection.d.ts

@@ -0,0 +1,43 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.page-section",
+  "title": "<PageSection> Layout Component",
+  "category": "feature"
+}
+*/
+import { type SectionTag } from '../shared/common';
+import { type SpacingSize } from '@pithyjs/design-system';
+/** @codexApi {"parent":"pithy.ui-kit.page-section","name":"PageSectionProps","stability":"stable","signature":"interface PageSectionProps"} */
+export interface PageSectionProps {
+    /** Vertical padding — maps to u-py-* utilities (default: "lg") */
+    spacing?: SpacingSize;
+    /** Apply max-width + centered layout with gutters (default: false) */
+    contained?: boolean;
+    /** Edge-to-edge viewport width breakout (default: false) */
+    fullBleed?: boolean;
+    /** Semantic HTML tag (default: "section") */
+    as?: SectionTag;
+    /** Optional anchor id */
+    id?: string;
+}
+/**
+ * Semantic page section wrapper with consistent vertical spacing,
+ * optional containment, and full-bleed support.
+ *
+ * Named `PageSection` (not `Section`) to avoid collision with the
+ * native HTML `<section>` element — same pattern as `NavLink`.
+ *
+ * @example
+ * ```html
+ * <PageSection spacing="'lg'" contained="true">
+ *   <h2>Features</h2>
+ *   <p>Content here</p>
+ * </PageSection>
+ * ```
+ */
+/** @codexApi {"parent":"pithy.ui-kit.page-section","name":"PageSection","stability":"stable","signature":"(props?: PageSectionProps) => { el: HTMLElement | DocumentFragment; destroy: () => void }"} */
+export declare function PageSection({ spacing: rawSpacing, contained, fullBleed, as: rawAs, id, }?: PageSectionProps): {
+    el: HTMLElement | DocumentFragment;
+    destroy: () => void;
+};
+//# sourceMappingURL=PageSection.d.ts.map

package/dist/layout/PageSection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PageSection.d.ts","sourceRoot":"","sources":["../../src/layout/PageSection.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAGF,OAAO,EAA0B,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE3E,OAAO,EAEL,KAAK,WAAW,EACjB,MAAM,wBAAwB,CAAC;AAEhC,+IAA+I;AAC/I,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,sEAAsE;IACtE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,6CAA6C;IAC7C,EAAE,CAAC,EAAE,UAAU,CAAC;IAChB,yBAAyB;IACzB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;GAcG;AACH,yMAAyM;AACzM,wBAAgB,WAAW,CAAC,EAC1B,OAAO,EAAE,UAAiB,EAC1B,SAAiB,EACjB,SAAiB,EACjB,EAAE,EAAE,KAAiB,EACrB,EAAc,GACf,GAAE,gBAAqB,GAAG;IACzB,EAAE,EAAE,WAAW,GAAG,gBAAgB,CAAC;IACnC,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CA0DA"}

package/dist/layout/PageSection.js

@@ -0,0 +1,75 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.page-section",
+  "title": "<PageSection> Layout Component",
+  "category": "feature"
+}
+*/
+import { renderChildren } from '@pithyjs/core';
+import { PY_CLASS, SECTION_TAGS } from '../shared/common';
+import { captureSlot } from '../shared/slots';
+import { CONTAINER_BREAKPOINTS, } from '@pithyjs/design-system';
+/**
+ * Semantic page section wrapper with consistent vertical spacing,
+ * optional containment, and full-bleed support.
+ *
+ * Named `PageSection` (not `Section`) to avoid collision with the
+ * native HTML `<section>` element — same pattern as `NavLink`.
+ *
+ * @example
+ * ```html
+ * <PageSection spacing="'lg'" contained="true">
+ *   <h2>Features</h2>
+ *   <p>Content here</p>
+ * </PageSection>
+ * ```
+ */
+/** @codexApi {"parent":"pithy.ui-kit.page-section","name":"PageSection","stability":"stable","signature":"(props?: PageSectionProps) => { el: HTMLElement | DocumentFragment; destroy: () => void }"} */
+export function PageSection({ spacing: rawSpacing = 'lg', contained = false, fullBleed = false, as: rawAs = 'section', id = undefined, } = {}) {
+    const hasOwn = Object.prototype.hasOwnProperty;
+    const validSpacing = hasOwn.call(PY_CLASS, rawSpacing);
+    const validAs = SECTION_TAGS.includes(rawAs);
+    if (import.meta.env?.DEV) {
+        if (!validSpacing) {
+            const valid = Object.keys(PY_CLASS).join(', ');
+            console.warn(`[<PageSection>] Invalid spacing value: "${rawSpacing}". Expected one of: ${valid}. Falling back to "lg".`);
+        }
+        if (!validAs) {
+            const valid = SECTION_TAGS.join(', ');
+            console.warn(`[<PageSection>] Invalid as value: "${rawAs}". Expected one of: ${valid}. Falling back to "section".`);
+        }
+        if (contained && fullBleed) {
+            console.warn(`[<PageSection>] "contained" and "fullBleed" are mutually exclusive. "fullBleed" takes precedence.`);
+        }
+    }
+    const spacing = validSpacing ? rawSpacing : 'lg';
+    const as = validAs ? rawAs : 'section';
+    // Create wrapper element
+    const wrapper = document.createElement(as);
+    wrapper.classList.add(PY_CLASS[spacing]);
+    // Optional anchor id
+    if (id)
+        wrapper.id = id;
+    // Full-bleed takes precedence over contained (mutually exclusive)
+    if (fullBleed) {
+        wrapper.style.width = '100vw';
+        wrapper.style.marginInline = 'calc(50% - 50vw)';
+    }
+    else if (contained) {
+        wrapper.style.maxWidth = CONTAINER_BREAKPOINTS.xl;
+        wrapper.style.marginInline = 'auto';
+        wrapper.style.paddingInline = 'var(--space-md)';
+    }
+    captureSlot(wrapper, 'default');
+    // Compile children through full pipeline
+    const { el: childFragment, destroy } = renderChildren();
+    wrapper.appendChild(childFragment);
+    return {
+        el: wrapper,
+        destroy: () => {
+            destroy();
+            wrapper.replaceChildren();
+        },
+    };
+}
+//# sourceMappingURL=PageSection.js.map

package/dist/layout/PageSection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PageSection.js","sourceRoot":"","sources":["../../src/layout/PageSection.ts"],"names":[],"mappings":"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"}

package/dist/layout/SmartContainer.d.ts

@@ -0,0 +1,66 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.smart-container",
+  "title": "<SmartContainer> Layout Component",
+  "category": "feature"
+}
+*/
+import { type AlignItems, type JustifyContent } from '../shared/common';
+import { type Recipe, type Density } from '../shared/smart-container';
+import { type SpacingSize } from '@pithyjs/design-system';
+/** @codexApi {"parent":"pithy.ui-kit.smart-container","name":"SmartContainerProps","stability":"stable","signature":"interface SmartContainerProps"} */
+export interface SmartContainerProps {
+    /** Layout recipe (default: "auto-grid") */
+    recipe?: Recipe;
+    /** Minimum item width for auto-grid recipe, e.g. "14rem", "250px" */
+    minItem?: string;
+    /** Gap between children — maps to u-gap-* utilities (default: "md") */
+    gap?: SpacingSize;
+    /** Density scaling: compact (0.9), normal (1.0), relaxed (1.25) */
+    density?: Density;
+    /** Cross-axis alignment — maps to u-items-* utilities */
+    align?: AlignItems;
+    /** Main-axis justification — maps to u-justify-* utilities */
+    justify?: JustifyContent;
+    /** Max column count for equal-cards recipe (2-6, default: 3) */
+    lanes?: number;
+    /** HTML tag to render (default: "div") */
+    as?: keyof HTMLElementTagNameMap;
+}
+/**
+ * Higher-level layout component providing 5 opinionated responsive
+ * layout recipes that adapt to container width via CSS container queries.
+ *
+ * Unlike Grid/Stack (low-level primitives), SmartContainer provides
+ * common layout patterns that "just work" responsively.
+ *
+ * @example
+ * ```html
+ * <!-- Auto-grid: items flow into columns based on minimum width -->
+ * <SmartContainer recipe="'auto-grid'" minItem="'14rem'" gap="'lg'">
+ *   <div>Card 1</div>
+ *   <div>Card 2</div>
+ *   <div>Card 3</div>
+ * </SmartContainer>
+ *
+ * <!-- Stack-to-row: vertical on mobile, horizontal on wider containers -->
+ * <SmartContainer recipe="'stack-to-row'">
+ *   <div>Left</div>
+ *   <div>Right</div>
+ * </SmartContainer>
+ *
+ * <!-- Equal cards: responsive grid capped at N columns -->
+ * <SmartContainer recipe="'equal-cards'" lanes="4">
+ *   <div>Card 1</div>
+ *   <div>Card 2</div>
+ *   <div>Card 3</div>
+ *   <div>Card 4</div>
+ * </SmartContainer>
+ * ```
+ */
+/** @codexApi {"parent":"pithy.ui-kit.smart-container","name":"SmartContainer","stability":"stable","signature":"(props?: SmartContainerProps) => { el: HTMLElement | DocumentFragment; destroy: () => void }"} */
+export declare function SmartContainer({ recipe: rawRecipe, minItem, gap: rawGap, density: rawDensity, align: rawAlign, justify: rawJustify, lanes: rawLanes, as, }?: SmartContainerProps): {
+    el: HTMLElement | DocumentFragment;
+    destroy: () => void;
+};
+//# sourceMappingURL=SmartContainer.d.ts.map

package/dist/layout/SmartContainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SmartContainer.d.ts","sourceRoot":"","sources":["../../src/layout/SmartContainer.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAIF,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAIL,KAAK,MAAM,EACX,KAAK,OAAO,EACb,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE/E,wJAAwJ;AACxJ,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB,mEAAmE;IACnE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yDAAyD;IACzD,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,EAAE,CAAC,EAAE,MAAM,qBAAqB,CAAC;CAClC;AAsBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,kNAAkN;AAClN,wBAAgB,cAAc,CAAC,EAC7B,MAAM,EAAE,SAAuB,EAC/B,OAAmB,EACnB,GAAG,EAAE,MAAa,EAClB,OAAO,EAAE,UAAqB,EAC9B,KAAK,EAAE,QAAoB,EAC3B,OAAO,EAAE,UAAsB,EAC/B,KAAK,EAAE,QAAY,EACnB,EAAU,GACX,GAAE,mBAAwB,GAAG;IAC5B,EAAE,EAAE,WAAW,GAAG,gBAAgB,CAAC;IACnC,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAmKA"}