@pithyjs/ui-kit 0.1.0-beta.0

package/dist/shared/textarea.js

@@ -0,0 +1,18 @@
+/** @codex { "id": "pithy.ui-kit.shared-textarea", "title": "Shared Textarea Constants", "category": "types" } */
+/**
+ * Shared constants for form Textarea component.
+ * Single source of truth for ID generation.
+ */
+// ---------------------------------------------------------------------------
+// Auto-generated IDs — enables FormField <label for=""> association
+// ---------------------------------------------------------------------------
+let textareaIdCounter = 0;
+/** @codexApi {"parent":"pithy.ui-kit.shared-textarea","name":"generateTextareaId","stability":"stable","signature":"() => string"} */
+export function generateTextareaId() {
+    return `ui-textarea-${++textareaIdCounter}`;
+}
+/** @codexApi {"parent":"pithy.ui-kit.shared-textarea","name":"resetTextareaIdCounter","stability":"stable","signature":"() => void"} */
+export function resetTextareaIdCounter() {
+    textareaIdCounter = 0;
+}
+//# sourceMappingURL=textarea.js.map

package/dist/shared/textarea.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"textarea.js","sourceRoot":"","sources":["../../src/shared/textarea.ts"],"names":[],"mappings":"AAAA,iHAAiH;AAEjH;;;GAGG;AAEH,8EAA8E;AAC9E,oEAAoE;AACpE,8EAA8E;AAE9E,IAAI,iBAAiB,GAAG,CAAC,CAAC;AAE1B,sIAAsI;AACtI,MAAM,UAAU,kBAAkB;IAChC,OAAO,eAAe,EAAE,iBAAiB,EAAE,CAAC;AAC9C,CAAC;AAED,wIAAwI;AACxI,MAAM,UAAU,sBAAsB;IACpC,iBAAiB,GAAG,CAAC,CAAC;AACxB,CAAC"}

package/dist/shared/toggle.d.ts

@@ -0,0 +1,6 @@
+/** @codex { "id": "pithy.ui-kit.shared-toggle", "title": "Shared Toggle Constants", "category": "types" } */
+/** @codexApi {"parent":"pithy.ui-kit.shared-toggle","name":"generateToggleId","stability":"stable","signature":"() => string"} */
+export declare function generateToggleId(): string;
+/** @codexApi {"parent":"pithy.ui-kit.shared-toggle","name":"resetToggleIdCounter","stability":"stable","signature":"() => void"} */
+export declare function resetToggleIdCounter(): void;
+//# sourceMappingURL=toggle.d.ts.map

package/dist/shared/toggle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toggle.d.ts","sourceRoot":"","sources":["../../src/shared/toggle.ts"],"names":[],"mappings":"AAAA,6GAA6G;AAa7G,kIAAkI;AAClI,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,oIAAoI;AACpI,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C"}

package/dist/shared/toggle.js

@@ -0,0 +1,19 @@
+/** @codex { "id": "pithy.ui-kit.shared-toggle", "title": "Shared Toggle Constants", "category": "types" } */
+/**
+ * Shared constants for the Toggle atom.
+ * Single source of truth for ID generation.
+ *
+ * **SSR:** Counter is module-level state. Call `resetToggleIdCounter()`
+ * between SSR requests to ensure deterministic IDs (same pattern as
+ * `resetCheckboxIdCounter()` / `resetRadioIdCounter()`).
+ */
+let toggleIdCounter = 0;
+/** @codexApi {"parent":"pithy.ui-kit.shared-toggle","name":"generateToggleId","stability":"stable","signature":"() => string"} */
+export function generateToggleId() {
+    return `ui-toggle-${++toggleIdCounter}`;
+}
+/** @codexApi {"parent":"pithy.ui-kit.shared-toggle","name":"resetToggleIdCounter","stability":"stable","signature":"() => void"} */
+export function resetToggleIdCounter() {
+    toggleIdCounter = 0;
+}
+//# sourceMappingURL=toggle.js.map

package/dist/shared/toggle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toggle.js","sourceRoot":"","sources":["../../src/shared/toggle.ts"],"names":[],"mappings":"AAAA,6GAA6G;AAE7G;;;;;;;GAOG;AAEH,IAAI,eAAe,GAAG,CAAC,CAAC;AAExB,kIAAkI;AAClI,MAAM,UAAU,gBAAgB;IAC9B,OAAO,aAAa,EAAE,eAAe,EAAE,CAAC;AAC1C,CAAC;AAED,oIAAoI;AACpI,MAAM,UAAU,oBAAoB;IAClC,eAAe,GAAG,CAAC,CAAC;AACtB,CAAC"}

package/dist/shared/types.d.ts

@@ -0,0 +1,41 @@
+/** @codex { "id": "pithy.ui-kit.shared-types", "title": "Shared UI-Kit Types", "category": "types" } */
+/**
+ * Shared types and utilities for ui-kit components.
+ */
+import type { ControlSize } from '@pithyjs/design-system';
+/** @codexApi {"parent":"pithy.ui-kit.shared-types","name":"SEMANTIC_COLORS","stability":"stable","signature":"readonly [\"primary\", \"secondary\", \"tertiary\", \"success\", \"info\", \"warning\", \"danger\"]"} */
+export declare const SEMANTIC_COLORS: readonly ["primary", "secondary", "tertiary", "success", "info", "warning", "danger"];
+/** @codexApi {"parent":"pithy.ui-kit.shared-types","name":"SemanticColor","stability":"stable","signature":"type SemanticColor = \"primary\" | \"secondary\" | \"tertiary\" | \"success\" | \"info\" | \"warning\" | \"danger\""} */
+export type SemanticColor = (typeof SEMANTIC_COLORS)[number];
+/** @codexApi {"parent":"pithy.ui-kit.shared-types","name":"CONTROL_SIZES","stability":"stable","signature":"readonly [\"sm\", \"md\", \"lg\"] satisfies readonly ControlSize[]"} */
+export declare const CONTROL_SIZES: readonly ["sm", "md", "lg"];
+/** @codexApi {"parent":"pithy.ui-kit.shared-types","name":"ORIENTATIONS","stability":"stable","signature":"readonly [\"vertical\", \"horizontal\"]"} */
+export declare const ORIENTATIONS: readonly ["vertical", "horizontal"];
+/** @codexApi {"parent":"pithy.ui-kit.shared-types","name":"Orientation","stability":"stable","signature":"type Orientation = \"vertical\" | \"horizontal\""} */
+export type Orientation = (typeof ORIENTATIONS)[number];
+/** @codexApi {"parent":"pithy.ui-kit.shared-types","name":"FormControlBaseProps","stability":"stable","signature":"interface FormControlBaseProps"} */
+export interface FormControlBaseProps {
+    /** Explicit element ID — overrides auto-generated ID. Used by FormField for label association. */
+    id?: string;
+    /** Accessible label — required for all form controls */
+    label: string;
+    /** Control size (default: "md") */
+    size?: ControlSize;
+    /** Disabled state — static boolean or signal accessor */
+    disabled?: boolean | (() => boolean);
+    /** Readonly state — static boolean or signal accessor */
+    readonly?: boolean | (() => boolean);
+    /** Required field — sets aria-required */
+    required?: boolean;
+    /** Error state — visual only, sets aria-invalid */
+    error?: boolean | (() => boolean);
+    /** Error message — shown below control when error is truthy */
+    errorMessage?: string | (() => string);
+    /** Helper text — persistent hint below control */
+    helperText?: string;
+    /** Success state — visual only */
+    success?: boolean | (() => boolean);
+    /** Loading state — shows spinner, sets aria-busy */
+    loading?: boolean | (() => boolean);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/shared/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"AAAA,wGAAwG;AAExG;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAM1D,uNAAuN;AACvN,eAAO,MAAM,eAAe,uFAGlB,CAAC;AACX,qOAAqO;AACrO,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAI7D,oLAAoL;AACpL,eAAO,MAAM,aAAa,6BAIiB,CAAC;AAI5C,wJAAwJ;AACxJ,eAAO,MAAM,YAAY,qCAAsC,CAAC;AAChE,gKAAgK;AAChK,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAMxD,uJAAuJ;AACvJ,MAAM,WAAW,oBAAoB;IACnC,kGAAkG;IAClG,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC;IACrC,yDAAyD;IACzD,QAAQ,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC;IACrC,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mDAAmD;IACnD,KAAK,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC;IAClC,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC;IACvC,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,OAAO,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC;IACpC,oDAAoD;IACpD,OAAO,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC;CACrC"}

package/dist/shared/types.js

@@ -0,0 +1,20 @@
+/** @codex { "id": "pithy.ui-kit.shared-types", "title": "Shared UI-Kit Types", "category": "types" } */
+import { COLOR_TOKENS } from '@pithyjs/design-system/colors';
+// -- Semantic colors (Button, Badge, Alert, Tag, etc.) ------------------------
+// Derived from design system COLOR_TOKENS — single source of truth.
+/** @codexApi {"parent":"pithy.ui-kit.shared-types","name":"SEMANTIC_COLORS","stability":"stable","signature":"readonly [\"primary\", \"secondary\", \"tertiary\", \"success\", \"info\", \"warning\", \"danger\"]"} */
+export const SEMANTIC_COLORS = [
+    ...COLOR_TOKENS.brand,
+    ...COLOR_TOKENS.status,
+];
+// -- Control sizes (runtime tuple synced with ControlSize) --------------------
+/** @codexApi {"parent":"pithy.ui-kit.shared-types","name":"CONTROL_SIZES","stability":"stable","signature":"readonly [\"sm\", \"md\", \"lg\"] satisfies readonly ControlSize[]"} */
+export const CONTROL_SIZES = [
+    'sm',
+    'md',
+    'lg',
+];
+// -- Orientation (axis vocabulary shared by Stack, Card, Divider, etc.) -------
+/** @codexApi {"parent":"pithy.ui-kit.shared-types","name":"ORIENTATIONS","stability":"stable","signature":"readonly [\"vertical\", \"horizontal\"]"} */
+export const ORIENTATIONS = ['vertical', 'horizontal'];
+//# sourceMappingURL=types.js.map

package/dist/shared/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"AAAA,wGAAwG;AAOxG,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAE7D,gFAAgF;AAChF,oEAAoE;AAEpE,uNAAuN;AACvN,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,GAAG,YAAY,CAAC,KAAK;IACrB,GAAG,YAAY,CAAC,MAAM;CACd,CAAC;AAIX,gFAAgF;AAEhF,oLAAoL;AACpL,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,IAAI;IACJ,IAAI;IACJ,IAAI;CACqC,CAAC;AAE5C,gFAAgF;AAEhF,wJAAwJ;AACxJ,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,UAAU,EAAE,YAAY,CAAU,CAAC"}

package/dist/structural/ErrorBoundary.d.ts

@@ -0,0 +1,18 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.error-boundary",
+  "title": "<ErrorBoundary> Structural Component",
+  "category": "feature"
+}
+*/
+/** @codexApi {"parent":"pithy.ui-kit.error-boundary","name":"ErrorBoundaryProps","stability":"stable","signature":"interface ErrorBoundaryProps"} */
+export interface ErrorBoundaryProps {
+    /** Called when an error is caught */
+    onError?: (error: Error) => void;
+}
+/** @codexApi {"parent":"pithy.ui-kit.error-boundary","name":"ErrorBoundary","stability":"stable","signature":"(props: ErrorBoundaryProps) => { el: DocumentFragment; destroy: () => void }"} */
+export declare function ErrorBoundary({ onError }?: ErrorBoundaryProps): {
+    el: DocumentFragment;
+    destroy: () => void;
+};
+//# sourceMappingURL=ErrorBoundary.d.ts.map

package/dist/structural/ErrorBoundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorBoundary.d.ts","sourceRoot":"","sources":["../../src/structural/ErrorBoundary.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAMF,qJAAqJ;AACrJ,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED,gMAAgM;AAChM,wBAAgB,aAAa,CAAC,EAAE,OAAO,EAAE,GAAE,kBAAuB,GAAG;IACnE,EAAE,EAAE,gBAAgB,CAAC;IACrB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAmIA"}

package/dist/structural/ErrorBoundary.js

@@ -0,0 +1,119 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.error-boundary",
+  "title": "<ErrorBoundary> Structural Component",
+  "category": "feature"
+}
+*/
+import { signal } from '@pithyjs/signals';
+import { compileNodes } from '@pithyjs/core';
+/** @codexApi {"parent":"pithy.ui-kit.error-boundary","name":"ErrorBoundary","stability":"stable","signature":"(props: ErrorBoundaryProps) => { el: DocumentFragment; destroy: () => void }"} */
+export function ErrorBoundary({ onError } = {}) {
+    // 1. Read child AST nodes from component context
+    const componentCtx = globalThis.__pithyComponentContext;
+    const childAstNodes = componentCtx?.__childAstNodes;
+    if (import.meta.env?.DEV) {
+        if (!childAstNodes || childAstNodes.length === 0) {
+            console.warn('[<ErrorBoundary>] No child AST nodes found. Ensure <ErrorBoundary> has children in the template.');
+        }
+    }
+    // 2. Separate into default and fallback slot nodes
+    const defaultNodes = [];
+    const fallbackNodes = [];
+    if (childAstNodes) {
+        for (const node of childAstNodes) {
+            if (node.directives?.slot === 'fallback' ||
+                node.attrs?.slot === 'fallback') {
+                // Strip slot attribute — these nodes are now direct children of the
+                // fallback container, not slot projections.
+                const cleaned = { ...node };
+                if (cleaned.attrs?.slot) {
+                    cleaned.attrs = { ...cleaned.attrs };
+                    delete cleaned.attrs.slot;
+                }
+                if (cleaned.directives?.slot) {
+                    cleaned.directives = { ...cleaned.directives };
+                    delete cleaned.directives.slot;
+                }
+                fallbackNodes.push(cleaned);
+            }
+            else {
+                defaultNodes.push(node);
+            }
+        }
+    }
+    // 3. Create error signal
+    const errorSignal = signal(null);
+    // 4. Build parent context (strip all internal __ properties)
+    const parentCtx = componentCtx
+        ? Object.fromEntries(Object.entries(componentCtx).filter(([k]) => !k.startsWith('__')))
+        : {};
+    // 5. Build boundary context with error signal injected
+    // The babel plugin's componentScopes declares `error` as an injected variable
+    // for ErrorBoundary, so it won't clash with parent scope identifiers.
+    const boundaryCtx = {
+        ...parentCtx,
+        __errorSignal: errorSignal,
+        error: errorSignal,
+    };
+    // 6. Build the complete boundary as a unified AST tree.
+    // By passing the entire tree to compileNodes in one shot, we guarantee that:
+    //  - The error boundary is registered (bindErrorBoundary step) BEFORE
+    //    child components are instantiated (bindComponentTags step)
+    //  - Structural directives (@if, @switch, @for) inside children work correctly
+    const uid = Math.random().toString(36).slice(2, 8);
+    const boundaryAst = [
+        {
+            type: 'element',
+            tagName: 'div',
+            nodeId: `__eb-root-${uid}`,
+            directives: {
+                error: '__errorSignal', // → data-error attr (pithyTreeToDom.ts:163)
+            },
+            children: [
+                ...defaultNodes,
+                {
+                    type: 'element',
+                    tagName: 'div',
+                    nodeId: `__eb-fallback-${uid}`,
+                    directives: {
+                        fallback: true, // → data-fallback attr (pithyTreeToDom.ts:168)
+                    },
+                    children: fallbackNodes.length > 0
+                        ? fallbackNodes
+                        : [
+                            {
+                                type: 'text',
+                                textContent: 'Something went wrong.',
+                                nodeId: `__eb-text-${uid}`,
+                            },
+                        ],
+                },
+            ],
+        },
+    ];
+    // 7. Compile with full pipeline (structural + non-structural directives)
+    const { el, destroy: destroyCompiled } = compileNodes(boundaryAst, boundaryCtx);
+    // 8. Set up onError callback via subscribe() (not effect())
+    // subscribe() avoids tracking signal reads inside the callback,
+    // which could cause infinite loops if the callback updates other signals.
+    const localDisposers = [];
+    if (onError) {
+        const unsubscribe = errorSignal.subscribe(err => {
+            if (err !== null) {
+                onError(err);
+            }
+        });
+        localDisposers.push(unsubscribe);
+    }
+    // 9. Return
+    return {
+        el,
+        destroy: () => {
+            for (const d of localDisposers)
+                d();
+            destroyCompiled();
+        },
+    };
+}
+//# sourceMappingURL=ErrorBoundary.js.map

package/dist/structural/ErrorBoundary.js.map

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

package/dist/structural/For.d.ts

@@ -0,0 +1,37 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.for",
+  "title": "<For> Structural Component",
+  "category": "feature"
+}
+*/
+import { type Signal } from '@pithyjs/signals';
+/** @codexApi {"parent":"pithy.ui-kit.for","name":"ForProps","stability":"stable","signature":"interface ForProps<T>"} */
+export interface ForProps<T = unknown> {
+    /** Reactive or static list of items to render */
+    list: Signal<T[]> | T[];
+    /** Key extractor — string property name or function */
+    trackBy?: string | ((item: T, index: number) => string);
+    /** Item variable name exposed to children (default: "item") */
+    as?: string;
+    /** Index variable name exposed to children (default: "index") */
+    indexAs?: string;
+    /** Count signal alias (default: "count") */
+    countAs?: string;
+    /** First signal alias (default: "first") */
+    firstAs?: string;
+    /** Last signal alias (default: "last") */
+    lastAs?: string;
+    /** Even signal alias (default: "even") */
+    evenAs?: string;
+    /** Odd signal alias (default: "odd") */
+    oddAs?: string;
+    /** Suppress the DEV warning when intentionally shadowing outer loop helpers */
+    allowShadow?: boolean;
+}
+/** @codexApi {"parent":"pithy.ui-kit.for","name":"For","stability":"stable","signature":"<T>(props: ForProps<T>) => { el: DocumentFragment; destroy: () => void }"} */
+export declare function For<T>({ list, trackBy, as: _as, indexAs: _indexAs, countAs: _countAs, firstAs: _firstAs, lastAs: _lastAs, evenAs: _evenAs, oddAs: _oddAs, allowShadow, }: ForProps<T>): {
+    el: DocumentFragment;
+    destroy: () => void;
+};
+//# sourceMappingURL=For.d.ts.map

package/dist/structural/For.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"For.d.ts","sourceRoot":"","sources":["../../src/structural/For.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,OAAO,EAAoB,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAKjE,yHAAyH;AACzH,MAAM,WAAW,QAAQ,CAAC,CAAC,GAAG,OAAO;IACnC,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;IACxB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;IACxD,+DAA+D;IAC/D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,uKAAuK;AACvK,wBAAgB,GAAG,CAAC,CAAC,EAAE,EACrB,IAAI,EACJ,OAAmB,EACnB,EAAE,EAAE,GAAY,EAChB,OAAO,EAAE,QAAkB,EAC3B,OAAO,EAAE,QAAkB,EAC3B,OAAO,EAAE,QAAkB,EAC3B,MAAM,EAAE,OAAgB,EACxB,MAAM,EAAE,OAAgB,EACxB,KAAK,EAAE,MAAc,EACrB,WAAmB,GACpB,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG;IAAE,EAAE,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CA0J7D"}

package/dist/structural/For.js

@@ -0,0 +1,129 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.for",
+  "title": "<For> Structural Component",
+  "category": "feature"
+}
+*/
+import { effect, isSignal } from '@pithyjs/signals';
+import { createLoopManager } from '@pithyjs/core';
+import { isValidJsIdentifier } from '@pithyjs/shared';
+/** @codexApi {"parent":"pithy.ui-kit.for","name":"For","stability":"stable","signature":"<T>(props: ForProps<T>) => { el: DocumentFragment; destroy: () => void }"} */
+export function For({ list, trackBy = undefined, as: _as = 'item', indexAs: _indexAs = 'index', countAs: _countAs = 'count', firstAs: _firstAs = 'first', lastAs: _lastAs = 'last', evenAs: _evenAs = 'even', oddAs: _oddAs = 'odd', allowShadow = false, }) {
+    let as = _as;
+    let indexAs = _indexAs;
+    let countAs = _countAs;
+    let firstAs = _firstAs;
+    let lastAs = _lastAs;
+    let evenAs = _evenAs;
+    let oddAs = _oddAs;
+    // Validate all alias props are valid JS identifiers (not reserved words).
+    // Fallback always runs (prevents broken templates in prod); warning is DEV-only.
+    const validateAlias = (value, name, fallback) => {
+        if (!isValidJsIdentifier(value)) {
+            if (import.meta.env?.DEV) {
+                console.warn(`[<For>] Invalid "${name}" value: "${value}". Must be a valid, non-reserved JS identifier. Falling back to "${fallback}".`);
+            }
+            return fallback;
+        }
+        return value;
+    };
+    as = validateAlias(as, 'as', 'item');
+    indexAs = validateAlias(indexAs, 'indexAs', 'index');
+    countAs = validateAlias(countAs, 'countAs', 'count');
+    firstAs = validateAlias(firstAs, 'firstAs', 'first');
+    lastAs = validateAlias(lastAs, 'lastAs', 'last');
+    evenAs = validateAlias(evenAs, 'evenAs', 'even');
+    oddAs = validateAlias(oddAs, 'oddAs', 'odd');
+    // 1. Read child AST nodes from component context
+    const componentCtx = globalThis.__pithyComponentContext;
+    const childAstNodes = componentCtx?.__childAstNodes;
+    if (!childAstNodes || childAstNodes.length === 0) {
+        if (import.meta.env?.DEV) {
+            console.warn('[<For>] No child AST nodes found. Ensure <For> has children in the template.');
+        }
+        const emptyFragment = document.createDocumentFragment();
+        return { el: emptyFragment, destroy: () => { } };
+    }
+    // 2. Build trackBy function
+    let trackByFn;
+    if (typeof trackBy === 'function') {
+        trackByFn = trackBy;
+    }
+    else if (typeof trackBy === 'string') {
+        trackByFn = (item) => String(item[trackBy]);
+    }
+    else {
+        trackByFn = (_item, index) => String(index);
+    }
+    // 3. Create anchor and fragment
+    const anchor = document.createComment('#for-component');
+    const fragment = document.createDocumentFragment();
+    fragment.appendChild(anchor);
+    // 4. Build parent context (strip all internal __ properties)
+    const parentCtx = componentCtx
+        ? Object.fromEntries(Object.entries(componentCtx).filter(([k]) => !k.startsWith('__')))
+        : {};
+    // Warn when nested <For> will shadow outer loop helpers without aliases
+    if (import.meta.env?.DEV && !allowShadow) {
+        const helperNames = [countAs, firstAs, lastAs, evenAs, oddAs];
+        const shadowedHelpers = helperNames.filter(name => typeof parentCtx[name] === 'function');
+        if (shadowedHelpers.length > 0) {
+            console.warn(`[<For>] Nested <For> detected. Helper signals (${shadowedHelpers.join(', ')}) ` +
+                'from the outer loop will be shadowed. Use countAs/firstAs/lastAs/evenAs/oddAs to alias them, ' +
+                'or pass allowShadow to suppress this warning.');
+        }
+    }
+    // 5. Delegate to createLoopManager with templateNodes
+    const loopManager = createLoopManager({
+        anchor,
+        trackByFn,
+        parentCtx,
+        itemVar: as,
+        indexVar: indexAs,
+        countVar: countAs,
+        firstVar: firstAs,
+        lastVar: lastAs,
+        evenVar: evenAs,
+        oddVar: oddAs,
+        templateNodes: childAstNodes,
+    });
+    // 6. Reactive effect that watches `list`
+    if (import.meta.env?.DEV) {
+        if (!isSignal(list) && Array.isArray(list)) {
+            console.warn("[<For>] list is a static array — updates won't be reactive. Wrap it in signal() for reactivity.");
+        }
+    }
+    const disposers = [];
+    const stopEffect = effect(() => {
+        let collection;
+        if (Array.isArray(list)) {
+            collection = list;
+        }
+        else if (isSignal(list)) {
+            collection = list();
+        }
+        else {
+            if (import.meta.env?.DEV) {
+                console.warn('[<For>] list prop is not an array or signal:', list);
+            }
+            collection = [];
+        }
+        if (!Array.isArray(collection)) {
+            if (import.meta.env?.DEV) {
+                console.warn('[<For>] list signal did not return an array:', collection);
+            }
+            collection = [];
+        }
+        loopManager.update(collection);
+    });
+    disposers.push(stopEffect);
+    // 7. Return fragment and destroy
+    const destroy = () => {
+        for (const d of disposers)
+            d();
+        loopManager.destroyAll();
+    };
+    return { el: fragment, destroy };
+}
+//# sourceMappingURL=For.js.map

package/dist/structural/For.js.map

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

package/dist/structural/Lazy.d.ts

@@ -0,0 +1,43 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.lazy",
+  "title": "<Lazy> Structural Component",
+  "category": "feature"
+}
+*/
+import { type Signal } from '@pithyjs/signals';
+import { type LazyHandle } from '@pithyjs/core';
+/** @codexApi {"parent":"pithy.ui-kit.lazy","name":"LazyProps","stability":"stable","signature":"interface LazyProps"} */
+export interface LazyProps {
+    /** Lazy handle created by lazy() — required */
+    load: LazyHandle<unknown>;
+    /** Trigger mode: 'visible' (default) loads on viewport entry, 'when' loads on condition */
+    trigger?: 'visible' | 'when';
+    /** Condition for trigger='when' — accepts Signal<boolean> or static boolean */
+    when?: Signal<boolean> | boolean;
+}
+/**
+ * Lazy-loads a component using the existing @defer directive.
+ *
+ * Delegates entirely to @defer + content projection —
+ * the existing framework handles IntersectionObserver, loading,
+ * timeout, retry, error boundaries, and cleanup.
+ *
+ * @example
+ * ```html
+ * <Lazy load="HeavyChart" trigger="'visible'">
+ *   <div slot="placeholder">Loading chart...</div>
+ *   <div slot="error">Failed to load</div>
+ * </Lazy>
+ *
+ * <Lazy load="ExpensiveTab" trigger="'when'" when="isTabVisible">
+ *   <span slot="placeholder">Loading...</span>
+ * </Lazy>
+ * ```
+ */
+/** @codexApi {"parent":"pithy.ui-kit.lazy","name":"Lazy","stability":"stable","signature":"(props: LazyProps) => { el: HTMLElement | DocumentFragment; destroy: () => void }"} */
+export declare function Lazy({ load, trigger, when, }: LazyProps): {
+    el: HTMLElement | DocumentFragment;
+    destroy: () => void;
+};
+//# sourceMappingURL=Lazy.d.ts.map

package/dist/structural/Lazy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Lazy.d.ts","sourceRoot":"","sources":["../../src/structural/Lazy.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,OAAO,EAAY,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAQ,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAEtD,yHAAyH;AACzH,MAAM,WAAW,SAAS;IACxB,+CAA+C;IAC/C,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;IAC1B,2FAA2F;IAC3F,OAAO,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IAC7B,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,kLAAkL;AAClL,wBAAgB,IAAI,CAAC,EACnB,IAAI,EACJ,OAAmB,EACnB,IAAgB,GACjB,EAAE,SAAS,GAAG;IAAE,EAAE,EAAE,WAAW,GAAG,gBAAgB,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAmBzE"}

package/dist/structural/Lazy.js

@@ -0,0 +1,47 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.lazy",
+  "title": "<Lazy> Structural Component",
+  "category": "feature"
+}
+*/
+import { isSignal } from '@pithyjs/signals';
+import { html } from '@pithyjs/core';
+/**
+ * Lazy-loads a component using the existing @defer directive.
+ *
+ * Delegates entirely to @defer + content projection —
+ * the existing framework handles IntersectionObserver, loading,
+ * timeout, retry, error boundaries, and cleanup.
+ *
+ * @example
+ * ```html
+ * <Lazy load="HeavyChart" trigger="'visible'">
+ *   <div slot="placeholder">Loading chart...</div>
+ *   <div slot="error">Failed to load</div>
+ * </Lazy>
+ *
+ * <Lazy load="ExpensiveTab" trigger="'when'" when="isTabVisible">
+ *   <span slot="placeholder">Loading...</span>
+ * </Lazy>
+ * ```
+ */
+/** @codexApi {"parent":"pithy.ui-kit.lazy","name":"Lazy","stability":"stable","signature":"(props: LazyProps) => { el: HTMLElement | DocumentFragment; destroy: () => void }"} */
+export function Lazy({ load, trigger = 'visible', when = undefined, }) {
+    if (trigger === 'when') {
+        const whenCondition = when !== undefined ? (isSignal(when) ? when : () => !!when) : () => false;
+        return html `
+      <div @defer="when" @load="load" @when="whenCondition()">
+        <slot name="placeholder"></slot>
+        <slot name="error"></slot>
+      </div>
+    `;
+    }
+    return html `
+    <div @defer="visible" @load="load">
+      <slot name="placeholder"></slot>
+      <slot name="error"></slot>
+    </div>
+  `;
+}
+//# sourceMappingURL=Lazy.js.map

package/dist/structural/Lazy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Lazy.js","sourceRoot":"","sources":["../../src/structural/Lazy.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,OAAO,EAAE,QAAQ,EAAe,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,IAAI,EAAmB,MAAM,eAAe,CAAC;AAYtD;;;;;;;;;;;;;;;;;;GAkBG;AACH,kLAAkL;AAClL,MAAM,UAAU,IAAI,CAAC,EACnB,IAAI,EACJ,OAAO,GAAG,SAAS,EACnB,IAAI,GAAG,SAAS,GACN;IACV,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,MAAM,aAAa,GACjB,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC;QAE5E,OAAO,IAAI,CAAA;;;;;KAKV,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAA;;;;;GAKV,CAAC;AACJ,CAAC"}

package/dist/structural/NavLink.d.ts

@@ -0,0 +1,45 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.nav-link",
+  "title": "<NavLink> Structural Component",
+  "category": "feature"
+}
+*/
+import type { PrefetchStrategy } from '@pithyjs/router';
+/** @codexApi {"parent":"pithy.ui-kit.nav-link","name":"NavLinkProps","stability":"stable","signature":"interface NavLinkProps"} */
+export interface NavLinkProps {
+    /** Target URL — required */
+    to: string;
+    /** Prefetch strategy (default: 'none') */
+    prefetch?: PrefetchStrategy;
+    /** CSS class when route is active (default: 'router-link-active') */
+    activeClass?: string;
+    /** Use exact path matching for active state (default: false) */
+    exactActive?: boolean;
+    /** Replace current history entry instead of push (default: false) */
+    replace?: boolean;
+    /** CSS class(es) forwarded to the inner <a> element */
+    linkClass?: string;
+}
+/**
+ * Router-aware anchor that delegates to the @routerLink directive.
+ *
+ * Named NavLink (not Link) to avoid collision with the HTML <link>
+ * void element — parse5 treats <link> as self-closing, so children
+ * would be lost.
+ *
+ * @example
+ * ```html
+ * <NavLink to="'/about'">About</NavLink>
+ *
+ * <NavLink to="'/dashboard'" prefetch="'hover'" activeClass="'is-active'" exactActive="true">
+ *   Dashboard
+ * </NavLink>
+ * ```
+ */
+/** @codexApi {"parent":"pithy.ui-kit.nav-link","name":"NavLink","stability":"stable","signature":"(props: NavLinkProps) => { el: HTMLElement | DocumentFragment; destroy: () => void }"} */
+export declare function NavLink({ to, prefetch, activeClass, exactActive, replace, linkClass, }: NavLinkProps): {
+    el: HTMLElement | DocumentFragment;
+    destroy: () => void;
+};
+//# sourceMappingURL=NavLink.d.ts.map

package/dist/structural/NavLink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NavLink.d.ts","sourceRoot":"","sources":["../../src/structural/NavLink.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAGF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,mIAAmI;AACnI,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,qEAAqE;IACrE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,4LAA4L;AAC5L,wBAAgB,OAAO,CAAC,EACtB,EAAE,EACF,QAAiB,EACjB,WAAkC,EAClC,WAAmB,EACnB,OAAe,EACf,SAAc,GACf,EAAE,YAAY,GAAG;IAAE,EAAE,EAAE,WAAW,GAAG,gBAAgB,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAW5E"}