@vertz/ui 0.2.14 → 0.2.16

package/dist/src/css/public.d.ts

@@ -27,6 +27,101 @@ type CSSOutput<T extends CSSInput = CSSInput> = { readonly [K in keyof T & strin
 * @returns Object with block names as keys (class name strings) and non-enumerable `css` property.
 */
 declare function css<T extends CSSInput>(input: T & { [K in keyof T & "css"]? : never }, filePath?: string): CSSOutput<T>;
+interface FontSrc {
+	path: string;
+	weight?: string | number;
+	style?: "normal" | "italic";
+}
+type FallbackFontName = "Arial" | "Times New Roman" | "Courier New";
+interface FontFallbackMetrics {
+	/** CSS ascent-override value, e.g., '94.52%' */
+	ascentOverride: string;
+	/** CSS descent-override value, e.g., '24.60%' */
+	descentOverride: string;
+	/** CSS line-gap-override value, e.g., '0.00%' */
+	lineGapOverride: string;
+	/** CSS size-adjust value, e.g., '104.88%' */
+	sizeAdjust: string;
+	/** System font used as fallback base. */
+	fallbackFont: FallbackFontName;
+}
+interface CompileFontsOptions {
+	/** Pre-computed fallback metrics per font key. Provided by @vertz/ui-server at build/SSR time. */
+	fallbackMetrics?: Record<string, FontFallbackMetrics>;
+}
+interface FontOptions {
+	/** Font weight: '100..1000' (variable) or 400 (fixed). */
+	weight: string | number;
+	/** Font style. @default 'normal' */
+	style?: "normal" | "italic";
+	/** Font-display strategy. @default 'swap' */
+	display?: "auto" | "block" | "swap" | "fallback" | "optional";
+	/** URL path(s) for local/self-hosted fonts. */
+	src?: string | FontSrc[];
+	/** Fallback font stack. */
+	fallback?: string[];
+	/** Font subsets (metadata only — subsetting is deferred to a future phase). @default ['latin'] */
+	subsets?: string[];
+	/** Unicode range for subsetting. */
+	unicodeRange?: string;
+	/**
+	* Control automatic fallback font metric adjustment for zero-CLS font loading.
+	* - true: auto-detect fallback base from `fallback` array (default)
+	* - false: disable
+	* - 'Arial' | 'Times New Roman' | 'Courier New': explicit base
+	* @default true
+	*/
+	adjustFontFallback?: boolean | FallbackFontName;
+}
+type FontStyle = "normal" | "italic";
+type FontDisplay = "auto" | "block" | "swap" | "fallback" | "optional";
+interface FontDescriptor {
+	readonly __brand: "FontDescriptor";
+	readonly family: string;
+	readonly weight: string;
+	readonly style: FontStyle;
+	readonly display: FontDisplay;
+	readonly src?: string | FontSrc[];
+	readonly fallback: string[];
+	readonly subsets: string[];
+	readonly unicodeRange?: string;
+	readonly adjustFontFallback: boolean | FallbackFontName;
+}
+/** Structured description of a resource to preload. */
+interface PreloadItem {
+	href: string;
+	as: "font" | "image" | "style" | "script";
+	type?: string;
+	crossorigin?: boolean;
+}
+interface CompiledFonts {
+	/** @font-face declarations. */
+	fontFaceCss: string;
+	/** :root { --font-<key>: ...; } block (for standalone use). */
+	cssVarsCss: string;
+	/** Individual CSS var lines (e.g., '  --font-sans: ...;') for merging into an existing :root. */
+	cssVarLines: string[];
+	/** <link rel="preload"> HTML tags for font files. */
+	preloadTags: string;
+	/** Structured preload data for generating HTTP Link headers. */
+	preloadItems: PreloadItem[];
+}
+/**
+* Create a font descriptor for use in theme definitions.
+*
+* @param family - The font family name (e.g., 'DM Sans').
+* @param options - Font configuration.
+* @returns A FontDescriptor.
+*/
+declare function font(family: string, options: FontOptions): FontDescriptor;
+/**
+* Compile font descriptors into CSS and preload tags.
+*
+* @param fonts - A map of token key → FontDescriptor.
+* @param options - Optional compilation settings (e.g., pre-computed fallback metrics).
+* @returns Compiled @font-face CSS, CSS var lines, and preload link tags.
+*/
+declare function compileFonts(fonts: Record<string, FontDescriptor>, options?: CompileFontsOptions): CompiledFonts;
 /** Input to globalCss(): selector → property-value map. */
 type GlobalCSSInput = Record<string, Record<string, string>>;
 /** Output of globalCss(): extracted CSS string. */
@@ -65,6 +160,8 @@ interface ThemeInput {
 	colors: ColorTokens;
 	/** Spacing scale tokens. */
 	spacing?: SpacingTokens;
+	/** Font descriptors keyed by token name (e.g., sans, mono, display). */
+	fonts?: Record<string, FontDescriptor>;
 }
 /** The structured theme object returned by defineTheme(). */
 interface Theme {
@@ -72,6 +169,8 @@ interface Theme {
 	colors: ColorTokens;
 	/** Spacing scale tokens. */
 	spacing?: SpacingTokens;
+	/** Font descriptors keyed by token name. */
+	fonts?: Record<string, FontDescriptor>;
 }
 /** Output of compileTheme(). */
 interface CompiledTheme {
@@ -79,6 +178,15 @@ interface CompiledTheme {
 	css: string;
 	/** Flat list of token dot-paths (e.g., 'primary.500', 'background'). */
 	tokens: string[];
+	/** Font preload link tags for injection into <head>. */
+	preloadTags: string;
+	/** Structured preload data for generating HTTP Link headers. */
+	preloadItems: PreloadItem[];
+}
+/** Options for compileTheme(). */
+interface CompileThemeOptions {
+	/** Pre-computed font fallback metrics for zero-CLS font loading. */
+	fallbackMetrics?: CompileFontsOptions["fallbackMetrics"];
 }
 /**
 * Define a theme with raw and contextual design tokens.
@@ -97,7 +205,7 @@ declare function defineTheme(input: ThemeInput): Theme;
 * @param theme - A theme object from defineTheme().
 * @returns Compiled CSS and token list.
 */
-declare function compileTheme(theme: Theme): CompiledTheme;
+declare function compileTheme(theme: Theme, options?: CompileThemeOptions): CompiledTheme;
 /** A child node: either a DOM Node or a string (text content). */
 type ThemeChild = Node | string;
 /** Props for ThemeProvider. */
@@ -151,4 +259,4 @@ interface VariantFunction<V extends VariantDefinitions> {
 * @returns A function that accepts variant props and returns a className string.
 */
 declare function variants<V extends VariantDefinitions>(config: VariantsConfig<V>): VariantFunction<V>;
-export { variants, s, globalCss, defineTheme, css, compileTheme, VariantsConfig, VariantProps, VariantFunction, ThemeProviderProps, ThemeProvider, ThemeInput, Theme, StyleEntry, GlobalCSSOutput, GlobalCSSInput, CompiledTheme, CSSOutput, CSSInput };
+export { variants, s, globalCss, font, defineTheme, css, compileTheme, compileFonts, VariantsConfig, VariantProps, VariantFunction, ThemeProviderProps, ThemeProvider, ThemeInput, Theme, StyleEntry, PreloadItem, GlobalCSSOutput, GlobalCSSInput, FontSrc, FontOptions, FontFallbackMetrics, FontDescriptor, FallbackFontName, CompiledTheme, CompiledFonts, CompileThemeOptions, CompileFontsOptions, CSSOutput, CSSInput };

package/dist/src/css/public.js

@@ -1,22 +1,26 @@
 import {
   ThemeProvider,
+  compileFonts,
   compileTheme,
   css,
   defineTheme,
+  font,
   globalCss,
   s,
   variants
-} from "../../shared/chunk-c9xxsrat.js";
-import"../../shared/chunk-j6qyxfdc.js";
+} from "../../shared/chunk-dhehvmj0.js";
+import"../../shared/chunk-vndfjfdy.js";
 import"../../shared/chunk-prj7nm08.js";
-import"../../shared/chunk-h89w580h.js";
-import"../../shared/chunk-8hsz5y4a.js";
+import"../../shared/chunk-afawz764.js";
+import"../../shared/chunk-4fwcwxn6.js";
 export {
   variants,
   s,
   globalCss,
+  font,
   defineTheme,
   css,
   compileTheme,
+  compileFonts,
   ThemeProvider
 };

package/dist/src/form/public.d.ts

@@ -89,20 +89,44 @@ interface SdkMethodWithMeta<
 	};
 }
 /** Reserved property names that cannot be used as field names on FormInstance. */
-type ReservedFormNames = "submitting" | "dirty" | "valid" | "action" | "method" | "onSubmit" | "reset" | "setFieldError" | "submit" | "__bindElement";
-/** Mapped type providing FieldState for each field in TBody. */
+type ReservedFormNames = "submitting" | "dirty" | "valid" | "action" | "method" | "onSubmit" | "reset" | "setFieldError" | "submit" | "fields" | "__bindElement";
+/** Mapped type providing FieldState for each field in TBody (flat — no nested access). */
 type FieldAccessors<TBody> = { [K in keyof TBody] : FieldState<TBody[K]> };
+/** Built-in object types that should NOT recurse into NestedFieldAccessors. */
+type BuiltInObjects = Date | RegExp | File | Blob | Map<unknown, unknown> | Set<unknown>;
+/** FieldState signal/method property names that conflict with nested field names. */
+type FieldSignalReservedNames = "error" | "dirty" | "touched" | "value" | "setValue" | "reset";
+/** Check if any key of T collides with FieldState property names. */
+type HasReservedFieldName<T> = keyof T & FieldSignalReservedNames extends never ? false : true;
+/** Recursive field accessors for nested schemas. */
+type NestedFieldAccessors<T> = { [K in keyof T] : T[K] extends BuiltInObjects ? FieldState<T[K]> : T[K] extends Array<infer U> ? FieldState<T[K]> & ArrayFieldAccessors<U> : T[K] extends Record<string, unknown> ? HasReservedFieldName<T[K]> extends true ? {
+	__error: `Nested field name conflicts with FieldState property: ${keyof T[K] & FieldSignalReservedNames & string}`;
+} : FieldState<T[K]> & NestedFieldAccessors<T[K]> : FieldState<T[K]> };
+/** Array field accessors — numeric index access to element-level fields. */
+type ArrayFieldAccessors<U> = {
+	[index: number]: U extends BuiltInObjects ? FieldState<U> : U extends Record<string, unknown> ? FieldState<U> & NestedFieldAccessors<U> : FieldState<U>;
+};
+/** Deep partial utility for initial values. */
+type DeepPartial<T> = { [K in keyof T]? : T[K] extends Array<infer U> ? Array<DeepPartial<U>> : T[K] extends Record<string, unknown> ? DeepPartial<T[K]> : T[K] };
+/** Union of all valid dot-paths through a nested type. */
+type FieldPath<
+	T,
+	Prefix extends string = ""
+> = `${Prefix}${keyof T & string}` | { [K in keyof T & string] : T[K] extends Record<string, unknown> ? FieldPath<T[K], `${Prefix}${K}.`> : never }[keyof T & string];
+/** Mapped type providing typed field name strings for compile-time input validation. */
+type FieldNames<TBody> = { readonly [K in keyof TBody & string] : K };
 /** Base properties available on every form instance. */
 interface FormBaseProperties<TBody> {
 	action: string;
 	method: string;
 	onSubmit: (e: Event) => Promise<void>;
 	reset: () => void;
-	setFieldError: (field: keyof TBody & string, message: string) => void;
+	setFieldError: (field: FieldPath<TBody>, message: string) => void;
 	submit: (formData?: FormData) => Promise<void>;
 	submitting: Signal<boolean>;
 	dirty: ReadonlySignal<boolean>;
 	valid: ReadonlySignal<boolean>;
+	fields: FieldNames<TBody>;
 	__bindElement: (el: HTMLFormElement) => void;
 }
 /**
@@ -114,7 +138,7 @@ interface FormBaseProperties<TBody> {
 type FormInstance<
 	TBody,
 	_TResult
-> = keyof TBody & ReservedFormNames extends never ? FormBaseProperties<TBody> & FieldAccessors<TBody> : {
+> = keyof TBody & ReservedFormNames extends never ? FormBaseProperties<TBody> & NestedFieldAccessors<TBody> : {
 	__error: `Field name conflicts with reserved form property: ${keyof TBody & ReservedFormNames & string}`;
 };
 /** Options for creating a form instance. */
@@ -124,8 +148,8 @@ interface FormOptions<
 > {
 	/** Explicit schema for client-side validation before submission. */
 	schema?: FormSchema<TBody>;
-	/** Initial values for form fields. */
-	initial?: Partial<TBody> | (() => Partial<TBody>);
+	/** Initial values for form fields. Supports nested partial values. */
+	initial?: DeepPartial<TBody> | (() => DeepPartial<TBody>);
 	/** Callback invoked after a successful submission. */
 	onSuccess?: (result: TResult) => void;
 	/** Callback invoked when validation or submission fails. */
@@ -154,6 +178,8 @@ declare function form<
 interface FormDataOptions {
 	/** When true, coerces numeric strings to numbers and "true"/"false" to booleans. */
 	coerce?: boolean;
+	/** When true, parses dot-separated keys into nested objects (e.g., "address.street" → { address: { street: ... } }). */
+	nested?: boolean;
 }
 /**
 * Convert FormData to a plain object.
@@ -164,4 +190,4 @@ interface FormDataOptions {
 *   "true"/"false" become booleans.
 */
 declare function formDataToObject(formData: FormData, options?: FormDataOptions): Record<string, unknown>;
-export { validate, formDataToObject, form, createFieldState, ValidationResult, SdkMethodWithMeta, SdkMethod, FormSchema, FormOptions, FormInstance, FormDataOptions, FieldState };
+export { validate, formDataToObject, form, createFieldState, ValidationResult, SdkMethodWithMeta, SdkMethod, NestedFieldAccessors, FormSchema, FormOptions, FormInstance, FormDataOptions, FieldState, FieldPath, FieldNames, FieldAccessors, DeepPartial, ArrayFieldAccessors };

package/dist/src/form/public.js

@@ -3,8 +3,8 @@ import {
   form,
   formDataToObject,
   validate
-} from "../../shared/chunk-c30eg6wn.js";
-import"../../shared/chunk-8hsz5y4a.js";
+} from "../../shared/chunk-j09yyh34.js";
+import"../../shared/chunk-4fwcwxn6.js";
 export {
   validate,
   formDataToObject,