@pithyjs/ui-kit 0.1.0-beta.0

package/dist/organisms/forms/validation.js

@@ -0,0 +1,118 @@
+/** @codex { "id": "pithy.ui-kit.validation", "title": "Form Validation Engine", "category": "feature" } */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Practical email regex — matches user@host.tld without being overly strict */
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function isEmpty(value) {
+    return value == null || value === '' || value === false;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Validate a single value against one rule.
+ * Returns the error message string if the rule fails, or `null` if it passes.
+ *
+ * Non-required rules are skipped for empty values (standard HTML5 behavior):
+ * an empty optional field is valid; the "required" rule handles emptiness.
+ */
+/** @codexApi {"parent":"pithy.ui-kit.validation","name":"checkRule","stability":"stable","signature":"(rule: ValidationRule, value: unknown, allValues: Record<string, unknown>) => string | null"} */
+export function checkRule(rule, value, allValues) {
+    // "required" handles empty check itself; all other rules skip empty values
+    if (rule.type !== 'required' && isEmpty(value)) {
+        return null;
+    }
+    switch (rule.type) {
+        case 'required':
+            return isEmpty(value) ? rule.message : null;
+        case 'minLength': {
+            const threshold = Number(rule.value);
+            // Misconfigured threshold (undefined / non-numeric) → fail closed
+            if (!Number.isFinite(threshold))
+                return rule.message;
+            return String(value).length < threshold ? rule.message : null;
+        }
+        case 'maxLength': {
+            const threshold = Number(rule.value);
+            if (!Number.isFinite(threshold))
+                return rule.message;
+            return String(value).length > threshold ? rule.message : null;
+        }
+        case 'min': {
+            const threshold = Number(rule.value);
+            if (!Number.isFinite(threshold))
+                return rule.message;
+            // Fail closed on non-numeric input (e.g. "-", "abc") so partial/invalid
+            // numeric entries can't bypass the rule via NaN comparisons.
+            const n = Number(value);
+            if (!Number.isFinite(n))
+                return rule.message;
+            return n < threshold ? rule.message : null;
+        }
+        case 'max': {
+            const threshold = Number(rule.value);
+            if (!Number.isFinite(threshold))
+                return rule.message;
+            const n = Number(value);
+            if (!Number.isFinite(n))
+                return rule.message;
+            return n > threshold ? rule.message : null;
+        }
+        case 'pattern': {
+            // Misconfigured pattern (undefined / null / empty string) → fail closed.
+            // Without this guard, String(undefined) would compile to /undefined/ and
+            // "" would compile to /(?:)/ which matches everything.
+            if (rule.value == null || rule.value === '')
+                return rule.message;
+            let re;
+            try {
+                if (rule.value instanceof RegExp) {
+                    // Drop g/y so .test() stays stateless across calls.
+                    const flags = rule.value.flags.replace(/[gy]/g, '');
+                    re = new RegExp(rule.value.source, flags);
+                }
+                else {
+                    re = new RegExp(String(rule.value));
+                }
+            }
+            catch {
+                return rule.message;
+            }
+            return !re.test(String(value)) ? rule.message : null;
+        }
+        case 'email':
+            return !EMAIL_RE.test(String(value)) ? rule.message : null;
+        case 'url':
+            try {
+                const url = new URL(String(value));
+                // Only allow safe schemes — block javascript:, data:, etc.
+                if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+                    return rule.message;
+                }
+                return null;
+            }
+            catch {
+                return rule.message;
+            }
+        case 'custom':
+            return rule.validator?.(value, allValues) ?? null;
+        default:
+            return null;
+    }
+}
+/**
+ * Validate a single value against all its rules.
+ * Returns an array of error messages (empty array = valid).
+ */
+/** @codexApi {"parent":"pithy.ui-kit.validation","name":"validateField","stability":"stable","signature":"(value: unknown, rules: ValidationRule[], allValues: Record<string, unknown>) => string[]"} */
+export function validateField(value, rules, allValues) {
+    const errors = [];
+    for (const rule of rules) {
+        const msg = checkRule(rule, value, allValues);
+        if (msg)
+            errors.push(msg);
+    }
+    return errors;
+}
+//# sourceMappingURL=validation.js.map

package/dist/organisms/forms/validation.js.map

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

package/dist/organisms/navigation/Navbar.d.ts

@@ -0,0 +1,66 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.navbar",
+  "title": "<Navbar> Organism",
+  "category": "feature",
+  "risk": "high"
+}
+*/
+import { type PrefetchStrategy } from '@pithyjs/router';
+/** @codexApi {"parent":"pithy.ui-kit.navbar","name":"NavbarItem","stability":"stable","signature":"interface NavbarItem"} */
+export interface NavbarItem {
+    /** Link text */
+    label: string;
+    /** Link URL (validated via isSafeHref) */
+    href: string;
+    /** Exact pathname match for active state (default: false = prefix match) */
+    exactActive?: boolean;
+    /**
+     * Prefetch strategy for this item. Only used when the global PithyJS
+     * router is available; ignored for plain-anchor fallback.
+     * Defaults to "none".
+     */
+    prefetch?: PrefetchStrategy;
+}
+/**
+ * Brand image variant requires an alt. A discriminated union would force
+ * TypeScript callers to pair brandImageSrc with brandImageAlt, but the
+ * site builder passes plain JSON, so we also perform a runtime DEV check.
+ */
+/** @codexApi {"parent":"pithy.ui-kit.navbar","name":"NavbarProps","stability":"stable","signature":"interface NavbarProps"} */
+export interface NavbarProps {
+    /** REQUIRED — aria-label for <nav>. Page may have multiple navs. */
+    label: string;
+    /** Brand wordmark text (rendered beside the logo if both set). */
+    brand?: string;
+    /** Brand logo image URL. When set, brandImageAlt is required. */
+    brandImageSrc?: string;
+    /** Alt text for the brand logo image (REQUIRED when brandImageSrc is set). */
+    brandImageAlt?: string;
+    /** Href for the brand link (default: "/"). */
+    brandHref?: string;
+    /** Primary nav items (data-driven). */
+    items?: NavbarItem[];
+    /** Stick to the top of the viewport on scroll. */
+    sticky?: boolean;
+    /** Transparent background until scrolled (intended for use over a hero). */
+    transparent?: boolean;
+    /** Vertical density (default "comfortable"). */
+    density?: 'comfortable' | 'compact';
+    /** Skip-to-content link target id (default: "main-content"). */
+    skipToContentTarget?: string;
+    /** Optional anchor id on the <nav> element. */
+    id?: string;
+}
+/**
+ * Test-only: reset the module-level ref counters so one test's leaked state
+ * (e.g. a nav that opened but never closed) can't skew the next test's
+ * acquire logic. Not exported from the public barrel.
+ */
+export declare function __resetNavbarGlobalLocksForTest(): void;
+/** @codexApi {"parent":"pithy.ui-kit.navbar","name":"Navbar","stability":"stable","signature":"(props: NavbarProps) => { el: HTMLElement; destroy: () => void }"} */
+export declare function Navbar(props: NavbarProps): {
+    el: HTMLElement;
+    destroy: () => void;
+};
+//# sourceMappingURL=Navbar.d.ts.map

package/dist/organisms/navigation/Navbar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Navbar.d.ts","sourceRoot":"","sources":["../../../src/organisms/navigation/Navbar.ts"],"names":[],"mappings":"AAAA;;;;;;;EAOE;AAIF,OAAO,EAKL,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAC;AAMzB,6HAA6H;AAC7H,MAAM,WAAW,UAAU;IACzB,gBAAgB;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CAC7B;AAED;;;;GAIG;AACH,+HAA+H;AAC/H,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,kDAAkD;IAClD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,gDAAgD;IAChD,OAAO,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACpC,gEAAgE;IAChE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,+CAA+C;IAC/C,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAoDD;;;;GAIG;AACH,wBAAgB,+BAA+B,IAAI,IAAI,CAGtD;AAED,qKAAqK;AACrK,wBAAgB,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG;IAC1C,EAAE,EAAE,WAAW,CAAC;IAChB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAm3BA"}