@epoch32/visage 0.0.0 → 1.1.0

package/dist/style/component.d.ts

@@ -0,0 +1,49 @@
+import type { Child } from "../dom/render";
+import { type StyleDefinition } from "./create-style";
+export interface StyleProps {
+    children?: string | StyleDefinition | (() => string | StyleDefinition);
+    classes?: StyleDefinition | (() => StyleDefinition);
+    passToChildren?: boolean;
+    id?: string;
+}
+/**
+ * Scoped Component Style Block
+ *
+ * Automatically hashes and scopes CSS rules to the parent component/container,
+ * preventing style leaks and collisions. Supports CSS strings or JavaScript style objects.
+ *
+ * Examples:
+ *
+ * 1. Object syntax:
+ * ```tsx
+ * export function Card(props) {
+ *   return (
+ *     <div class="card">
+ *       <h2>{props.title}</h2>
+ *       <Style classes={{
+ *         card: { background: "var(--card-bg)", padding: "20px", borderRadius: "8px" },
+ *         "& h2": { fontSize: "1.2rem", color: "var(--text)" }
+ *       }} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * 2. Component Scoped CSS string:
+ * ```tsx
+ * export function StepItem(props) {
+ *   return (
+ *     <div class="step-node">
+ *       <span class="step-num">{props.step}</span>
+ *       <span>{props.title}</span>
+ *
+ *       <Style>{`
+ *         .step-node { display: flex; align-items: center; gap: 8px; }
+ *         .step-num { font-weight: 600; color: var(--primary); }
+ *       `}</Style>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function Style(props: StyleProps): Child;

package/dist/style/create-style.d.ts

@@ -0,0 +1,63 @@
+import type * as CSS from "csstype";
+import { type ClassValue } from "./cx";
+/**
+ * Standard CSS Properties interface with full TypeScript & VS Code IntelliSense,
+ * supporting nested pseudo-classes, descendant selectors, and custom CSS variables.
+ */
+export type CSSProperties = CSS.Properties<string | number> & {
+    [key: `&${string}`]: CSSProperties | undefined;
+    [key: `.${string}`]: CSSProperties | undefined;
+    [key: `:${string}`]: CSSProperties | undefined;
+    [key: `@media${string}`]: CSSProperties | undefined;
+    [key: `@keyframes${string}`]: Record<string, CSSProperties> | undefined;
+    [key: `${number}%`]: CSSProperties | undefined;
+    from?: CSSProperties;
+    to?: CSSProperties;
+    [customProp: `--${string}`]: string | number | undefined;
+};
+export type StyleDefinition = Record<string, CSSProperties>;
+export type StyleClasses<T extends string = string> = {
+    [K in T]: string;
+} & Record<string, any> & {
+    scope: string;
+    scopeAttr: string;
+    css: string;
+    cx: (...args: ClassValue[]) => string;
+};
+/**
+ * Convert a JavaScript object style dictionary into standard CSS
+ */
+export declare function objectToCSS(classes: Record<string, any>): string;
+/**
+ * Define scoped CSS styles with type-safe class name mappings
+ *
+ * Supports tagged template literals, string CSS, or JavaScript style objects:
+ *
+ * 1. Object syntax with full VS Code CSS IntelliSense:
+ * ```tsx
+ * const styles = createStyle({
+ *   card: { background: "var(--card-bg)", padding: "16px", display: "flex" },
+ *   button: { background: "var(--primary)", "&:hover": { background: "var(--primary-hover)" } }
+ * });
+ * ```
+ *
+ * 2. Tagged template literal syntax:
+ * ```tsx
+ * const styles = createStyle`
+ *   .card { padding: 16px; border-radius: 8px; }
+ *   .active { color: var(--primary); }
+ * `;
+ * ```
+ */
+export declare function createStyle<T extends string = string>(templateOrObject: string | TemplateStringsArray | StyleDefinition, ...valuesOrOptions: any[]): StyleClasses<T>;
+/**
+ * Tagged template for defining a single scoped CSS class
+ */
+export declare function css(strings: TemplateStringsArray, ...values: any[]): string;
+/**
+ * Hook to inject dynamic or component-level CSS with automatic cleanup
+ */
+export declare function useStyle(cssInput: string | StyleDefinition | (() => string | StyleDefinition), options?: {
+    passToChildren?: boolean;
+    id?: string;
+}): string;

package/dist/style/cx.d.ts

@@ -0,0 +1,18 @@
+export type ClassValue = string | number | boolean | null | undefined | (() => any) | ClassValue[] | Record<string, any>;
+/**
+ * Check if a class value tree contains any reactive signal or function getters
+ */
+export declare function hasReactiveClass(val: any): boolean;
+/**
+ * Normalize dynamic classes from strings, numbers, arrays, and objects
+ */
+export declare function normalizeClass(val: any): string;
+/**
+ * Flexible classnames utility for combining conditional classes
+ *
+ * Example:
+ * ```ts
+ * cx("btn", { active: isActive(), disabled: !isEnabled() }, ["extra-1", extraClass])
+ * ```
+ */
+export declare function cx(...args: ClassValue[]): string;

package/dist/style/hash.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Fast 32-bit FNV-1a deterministic string hashing algorithm
+ */
+export declare function hashString(str: string): string;
+/**
+ * Generate a deterministic scope identifier for CSS blocks
+ */
+export declare function getScopeId(css: string, prefix?: string): string;

package/dist/style/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./component";
+export * from "./create-style";
+export * from "./cx";
+export * from "./hash";
+export * from "./layout";
+export * from "./manager";
+export * from "./parser";
+export * from "./scale";

package/dist/{src/style → style}/index.js

@@ -848,10 +848,12 @@ class Signal {
   _value;
   _subscribers = new Set;
   _equals;
+  _onSet;
   version = 0;
-  constructor(initialValue, equals) {
+  constructor(initialValue, equals, onSet) {
     this._value = initialValue;
     this._equals = equals ?? Object.is;
+    this._onSet = onSet;
   }
   get() {
     if (currentSubscriber !== null && currentSubscriber.state !== 3 /* DISPOSED */) {
@@ -876,6 +878,9 @@ class Signal {
     }
     this._value = newValue;
     this.version++;
+    if (this._onSet) {
+      this._onSet(newValue);
+    }
     batch(() => {
       this.notify();
     });
@@ -901,11 +906,91 @@ class Signal {
     }
   }
 }
+function resolveStorage(storageOption) {
+  if (storageOption && typeof storageOption === "object") {
+    return storageOption;
+  }
+  if (storageOption === "session") {
+    try {
+      if (typeof sessionStorage !== "undefined")
+        return sessionStorage;
+    } catch {}
+    try {
+      if (typeof window !== "undefined" && window.sessionStorage) {
+        return window.sessionStorage;
+      }
+    } catch {}
+    try {
+      if (typeof globalThis !== "undefined" && globalThis.sessionStorage) {
+        return globalThis.sessionStorage;
+      }
+    } catch {}
+    return null;
+  }
+  try {
+    if (typeof localStorage !== "undefined")
+      return localStorage;
+  } catch {}
+  try {
+    if (typeof window !== "undefined" && window.localStorage) {
+      return window.localStorage;
+    }
+  } catch {}
+  try {
+    if (typeof globalThis !== "undefined" && globalThis.localStorage) {
+      return globalThis.localStorage;
+    }
+  } catch {}
+  return null;
+}
 function signal(initialValue, optionsOrEquals) {
   const equals = typeof optionsOrEquals === "function" ? optionsOrEquals : optionsOrEquals?.equals;
   const isInternal = typeof optionsOrEquals === "object" ? optionsOrEquals?.internal : false;
   const customName = typeof optionsOrEquals === "object" ? optionsOrEquals?.name : undefined;
-  const s = new Signal(initialValue, equals);
+  const persistOption = typeof optionsOrEquals === "object" ? optionsOrEquals?.persist : undefined;
+  const persistConfig = persistOption ? typeof persistOption === "string" ? { key: persistOption } : persistOption : undefined;
+  let effectiveInitial = initialValue;
+  const storage = persistConfig ? resolveStorage(persistConfig.storage) : null;
+  const serialize = persistConfig?.serialize ?? JSON.stringify;
+  const deserialize = persistConfig?.deserialize ?? JSON.parse;
+  if (persistConfig && storage) {
+    try {
+      const stored = storage.getItem(persistConfig.key);
+      if (stored !== null) {
+        effectiveInitial = deserialize(stored);
+      }
+    } catch {}
+  }
+  let isSyncing = false;
+  const onSet = persistConfig && storage ? (val) => {
+    if (isSyncing)
+      return;
+    try {
+      storage.setItem(persistConfig.key, serialize(val));
+    } catch {}
+  } : undefined;
+  const s = new Signal(effectiveInitial, equals, onSet);
+  if (persistConfig && storage && (persistConfig.syncTabs ?? true) && typeof window !== "undefined" && typeof window.addEventListener === "function") {
+    const onStorage = (e) => {
+      if (e.key === persistConfig.key) {
+        try {
+          const nextVal = e.newValue !== null ? deserialize(e.newValue) : initialValue;
+          isSyncing = true;
+          try {
+            s.set(nextVal);
+          } finally {
+            isSyncing = false;
+          }
+        } catch {}
+      }
+    };
+    window.addEventListener("storage", onStorage);
+    if (currentScope) {
+      currentScope.addCleanup(() => {
+        window.removeEventListener("storage", onStorage);
+      });
+    }
+  }
   const accessor = (...args) => {
     if (args.length === 0) {
       return s.get();

package/dist/style/layout.d.ts

@@ -0,0 +1,129 @@
+import type { Child } from "../dom";
+import type { ClassProp, HTMLAttributes } from "../jsx-runtime/jsx";
+export interface BaseLayoutProps extends HTMLAttributes<HTMLDivElement> {
+    as?: string;
+    gap?: number | string;
+    p?: number | string;
+    px?: number | string;
+    py?: number | string;
+    pt?: number | string;
+    pb?: number | string;
+    pl?: number | string;
+    pr?: number | string;
+    m?: number | string;
+    mx?: number | string;
+    my?: number | string;
+    mt?: number | string;
+    mb?: number | string;
+    ml?: number | string;
+    mr?: number | string;
+    w?: number | string;
+    h?: number | string;
+    minW?: number | string;
+    maxW?: number | string;
+    minH?: number | string;
+    maxH?: number | string;
+    class?: ClassProp;
+    className?: ClassProp;
+    style?: any;
+    children?: Child;
+    [key: string]: any;
+}
+export interface StackProps extends BaseLayoutProps {
+    align?: "start" | "center" | "end" | "stretch" | "baseline";
+    justify?: "start" | "center" | "end" | "between" | "around" | "evenly";
+    direction?: "vertical" | "horizontal";
+    reversed?: boolean;
+    wrap?: boolean | "wrap" | "nowrap" | "wrap-reverse";
+    inline?: boolean;
+}
+/**
+ * <Stack> Layout Primitive
+ *
+ * Vertical (column) layout by default. Provides zero margin collapse,
+ * built-in spatial scale gap, and automatic flex overflow containment.
+ *
+ * @example
+ * <Stack gap={4} align="center">
+ *   <Header />
+ *   <Content />
+ * </Stack>
+ */
+export declare function Stack(props: StackProps): Child;
+export interface RowProps extends BaseLayoutProps {
+    align?: "start" | "center" | "end" | "stretch" | "baseline";
+    justify?: "start" | "center" | "end" | "between" | "around" | "evenly";
+    reversed?: boolean;
+    wrap?: boolean | "wrap" | "nowrap" | "wrap-reverse";
+    inline?: boolean;
+}
+/**
+ * <Row> Layout Primitive
+ *
+ * Horizontal row layout with sensible vertical centering (align="center") by default.
+ *
+ * @example
+ * <Row gap={3} justify="between">
+ *   <Avatar />
+ *   <Typography>Online</Typography>
+ * </Row>
+ */
+export declare function Row(props: RowProps): Child;
+export interface CenterProps extends BaseLayoutProps {
+    inline?: boolean;
+}
+/**
+ * <Center> Layout Primitive
+ *
+ * Centers child content horizontally and vertically without CSS boilerplate.
+ *
+ * @example
+ * <Center h="screen">
+ *   <Spinner />
+ * </Center>
+ */
+export declare function Center(props: CenterProps): Child;
+export interface GridProps extends BaseLayoutProps {
+    columns?: number | string;
+    minChildWidth?: number | string;
+    rows?: number | string;
+    rowGap?: number | string;
+    colGap?: number | string;
+    align?: "start" | "center" | "end" | "stretch";
+    justify?: "start" | "center" | "end" | "stretch";
+    inline?: boolean;
+}
+/**
+ * <Grid> Layout Primitive
+ *
+ * Effortless CSS Grid. Specify fixed columns or a responsive minChildWidth
+ * to achieve fluid wrapping grids without writing complex media queries.
+ *
+ * @example
+ * // Responsive auto-wrapping grid
+ * <Grid minChildWidth={260} gap={4}>
+ *   <Card />
+ *   <Card />
+ * </Grid>
+ */
+export declare function Grid(props: GridProps): Child;
+export interface SpacerProps extends BaseLayoutProps {
+    size?: number | string;
+    x?: number | string;
+    y?: number | string;
+    flex?: boolean | number;
+}
+/**
+ * <Spacer> Layout Primitive
+ *
+ * Creates flexible pushing space in Rows/Stacks (defaults to flex: 1)
+ * or creates a dedicated spatial gap block when given size.
+ *
+ * @example
+ * <Row>
+ *   <Logo />
+ *   <Spacer />
+ *   <UserProfile />
+ * </Row>
+ */
+export declare function Spacer(props: SpacerProps): Child;

package/dist/style/manager.d.ts

@@ -0,0 +1,31 @@
+export interface InjectedStyle {
+    id: string;
+    css: string;
+    count: number;
+    element?: HTMLStyleElement;
+}
+export declare class StyleManager {
+    private _styles;
+    private _ssrStyles;
+    /**
+     * Inject CSS into the document head or SSR registry
+     */
+    inject(id: string, css: string): () => void;
+    /**
+     * Check if a style scope is currently registered
+     */
+    has(id: string): boolean;
+    /**
+     * Extract all styles collected during Server-Side Rendering (SSR)
+     */
+    extractSSRStyles(): string;
+    /**
+     * Clear all registered and SSR styles
+     */
+    clear(): void;
+}
+export declare const styleManager: StyleManager;
+/**
+ * Helper to get SSR style tag HTML
+ */
+export declare function extractStyleTags(): string;

package/dist/style/parser.d.ts

@@ -0,0 +1,12 @@
+export interface ScopeOptions {
+    scopeId: string;
+    passToChildren?: boolean;
+}
+/**
+ * Scope a single CSS selector string with the given scope identifier
+ */
+export declare function scopeSelector(selector: string, options: ScopeOptions): string;
+/**
+ * Full CSS block scoping transformer
+ */
+export declare function scopeCSS(css: string, options: ScopeOptions): string;

package/dist/style/scale.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Visage Spatial Engine & Style Primitives
+ *
+ * Eliminates measurement fatigue, layout bugs, and manual viewport calculations.
+ * Standardizes on a crisp 4px spatial scale, semantic viewport intents,
+ * fluid clamp calculations, and typed visual design tokens.
+ */
+export declare const UNITLESS_PROPERTIES: Set<string>;
+export declare const DIMENSION_KEYWORDS: Record<string, string>;
+/**
+ * Resolves a spatial scale step or dimensional intent to a valid CSS measurement.
+ * Numbers map to the 4px engineering grid (1 = 4px, 2 = 8px, 4 = 16px, 8 = 32px).
+ *
+ * @example
+ * space(1)        // "4px"
+ * space(2)        // "8px"
+ * space(4)        // "16px"
+ * space(6)        // "24px"
+ * space("full")   // "100%"
+ * space("screen") // "100dvh"
+ */
+export declare function space(val: number | string | undefined | null): string;
+/**
+ * Resolves width, height, or grid sizing into valid CSS.
+ * Small numbers (<= 48) map to the 4px scale, while larger numbers (> 48)
+ * are treated as explicit pixel dimensions.
+ */
+export declare function resolveDimension(val: number | string | undefined | null): string;
+/**
+ * Explicit raw pixel measurement helper.
+ */
+export declare function px(val: number): string;
+/**
+ * Explicit rem measurement helper.
+ */
+export declare function rem(val: number): string;
+/**
+ * Explicit em measurement helper.
+ */
+export declare function em(val: number): string;
+/**
+ * Computes an optimal fluid clamp() expression.
+ * Eliminates the math nightmare of manual linear viewport interpolation slopes.
+ *
+ * @param minPx Minimum size in pixels at mobile viewport
+ * @param maxPx Maximum size in pixels at desktop viewport
+ * @param options Min/max viewport bounds (defaults to 375px mobile and 1280px desktop)
+ *
+ * @example
+ * fluid(16, 32)
+ * // clamp(16px, 9.38px + 1.77vw, 32px)
+ */
+export declare function fluid(minPx: number, maxPx: number, options?: {
+    minVw?: number;
+    maxVw?: number;
+}): string;
+export type ShadowVariant = "none" | "sm" | "md" | "lg" | "xl" | "soft" | "glow" | "inner";
+export declare const SHADOW_PRESETS: Record<ShadowVariant, string>;
+/**
+ * Returns typed box-shadow tokens designed for high-contrast optical depth.
+ */
+export declare function shadow(variant: ShadowVariant | string): string;
+export type RadiusVariant = "none" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "full" | number;
+export declare const RADIUS_PRESETS: Record<string, string>;
+/**
+ * Returns typed border-radius tokens or scale numbers.
+ */
+export declare function radius(variant: RadiusVariant): string;
+export interface GlassOptions {
+    blur?: number | string;
+    tint?: string;
+    border?: string;
+}
+/**
+ * Generates tactile glassmorphism CSS styles with backdrop filters and frosted borders.
+ */
+export declare function glass(options?: GlassOptions): Record<string, string>;
+/**
+ * Formats a style property value for direct DOM binding or SSR generation.
+ * Handles automatic unit resolution, dimension keywords, and custom CSS variables.
+ */
+export declare function formatStyleProp(prop: string, val: any): string;

package/dist/template/index.d.ts

@@ -0,0 +1 @@
+export { html, template } from "./template";

package/dist/{src/template → template}/index.js

@@ -431,10 +431,12 @@ class Signal {
   _value;
   _subscribers = new Set;
   _equals;
+  _onSet;
   version = 0;
-  constructor(initialValue, equals) {
+  constructor(initialValue, equals, onSet) {
     this._value = initialValue;
     this._equals = equals ?? Object.is;
+    this._onSet = onSet;
   }
   get() {
     if (currentSubscriber !== null && currentSubscriber.state !== 3 /* DISPOSED */) {
@@ -459,6 +461,9 @@ class Signal {
     }
     this._value = newValue;
     this.version++;
+    if (this._onSet) {
+      this._onSet(newValue);
+    }
     batch(() => {
       this.notify();
     });
@@ -484,11 +489,91 @@ class Signal {
     }
   }
 }
+function resolveStorage(storageOption) {
+  if (storageOption && typeof storageOption === "object") {
+    return storageOption;
+  }
+  if (storageOption === "session") {
+    try {
+      if (typeof sessionStorage !== "undefined")
+        return sessionStorage;
+    } catch {}
+    try {
+      if (typeof window !== "undefined" && window.sessionStorage) {
+        return window.sessionStorage;
+      }
+    } catch {}
+    try {
+      if (typeof globalThis !== "undefined" && globalThis.sessionStorage) {
+        return globalThis.sessionStorage;
+      }
+    } catch {}
+    return null;
+  }
+  try {
+    if (typeof localStorage !== "undefined")
+      return localStorage;
+  } catch {}
+  try {
+    if (typeof window !== "undefined" && window.localStorage) {
+      return window.localStorage;
+    }
+  } catch {}
+  try {
+    if (typeof globalThis !== "undefined" && globalThis.localStorage) {
+      return globalThis.localStorage;
+    }
+  } catch {}
+  return null;
+}
 function signal(initialValue, optionsOrEquals) {
   const equals = typeof optionsOrEquals === "function" ? optionsOrEquals : optionsOrEquals?.equals;
   const isInternal = typeof optionsOrEquals === "object" ? optionsOrEquals?.internal : false;
   const customName = typeof optionsOrEquals === "object" ? optionsOrEquals?.name : undefined;
-  const s = new Signal(initialValue, equals);
+  const persistOption = typeof optionsOrEquals === "object" ? optionsOrEquals?.persist : undefined;
+  const persistConfig = persistOption ? typeof persistOption === "string" ? { key: persistOption } : persistOption : undefined;
+  let effectiveInitial = initialValue;
+  const storage = persistConfig ? resolveStorage(persistConfig.storage) : null;
+  const serialize = persistConfig?.serialize ?? JSON.stringify;
+  const deserialize = persistConfig?.deserialize ?? JSON.parse;
+  if (persistConfig && storage) {
+    try {
+      const stored = storage.getItem(persistConfig.key);
+      if (stored !== null) {
+        effectiveInitial = deserialize(stored);
+      }
+    } catch {}
+  }
+  let isSyncing = false;
+  const onSet = persistConfig && storage ? (val) => {
+    if (isSyncing)
+      return;
+    try {
+      storage.setItem(persistConfig.key, serialize(val));
+    } catch {}
+  } : undefined;
+  const s = new Signal(effectiveInitial, equals, onSet);
+  if (persistConfig && storage && (persistConfig.syncTabs ?? true) && typeof window !== "undefined" && typeof window.addEventListener === "function") {
+    const onStorage = (e) => {
+      if (e.key === persistConfig.key) {
+        try {
+          const nextVal = e.newValue !== null ? deserialize(e.newValue) : initialValue;
+          isSyncing = true;
+          try {
+            s.set(nextVal);
+          } finally {
+            isSyncing = false;
+          }
+        } catch {}
+      }
+    };
+    window.addEventListener("storage", onStorage);
+    if (currentScope) {
+      currentScope.addCleanup(() => {
+        window.removeEventListener("storage", onStorage);
+      });
+    }
+  }
   const accessor = (...args) => {
     if (args.length === 0) {
       return s.get();

package/dist/template/template.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Cache and clone pre-parsed HTML template strings with native browser cloneNode(true)
+ */
+export declare function template<T extends HTMLElement = HTMLElement>(htmlString: string): () => T;
+/**
+ * Tagged template literal for ultra-fast HTML string rendering with reactive signal bindings
+ */
+export declare function html(strings: TemplateStringsArray, ...values: any[]): HTMLElement | DocumentFragment;