@vertz/ui 0.2.0 → 0.2.1

package/dist/css/public.d.ts

@@ -1,14 +1,18 @@
+/** A raw CSS declaration: { property, value } for styles that can't be expressed as shorthands. */
+interface RawDeclaration {
+	property: string;
+	value: string;
+}
+/** A value within a nested selector array: shorthand string or raw declaration. */
+type StyleValue = string | RawDeclaration;
 /** A style entry in the array: either a shorthand string or an object for nested selectors. */
-type StyleEntry = string | Record<string, string[]>;
+type StyleEntry = string | Record<string, StyleValue[]>;
 /** Input to css(): a record of named style blocks. */
 type CSSInput = Record<string, StyleEntry[]>;
-/** Output of css(): a record of block names to class names, plus extracted CSS. */
-interface CSSOutput {
-	/** Map of block name → generated class name. */
-	classNames: Record<string, string>;
-	/** The extracted CSS string. */
-	css: string;
-}
+/** Output of css(): block names as top-level properties, plus non-enumerable `css`. */
+type CSSOutput<T extends CSSInput = CSSInput> = { readonly [K in keyof T & string] : string } & {
+	readonly css: string;
+};
 /**
 * Process a css() call and produce class names + extracted CSS.
 *
@@ -20,9 +24,9 @@ interface CSSOutput {
 *
 * @param input - Named style blocks.
 * @param filePath - Source file path for deterministic hashing.
-* @returns Class names map and extracted CSS.
+* @returns Object with block names as keys (class name strings) and non-enumerable `css` property.
 */
-declare function css(input: CSSInput, filePath?: string): CSSOutput;
+declare function css<T extends CSSInput>(input: T & { [K in keyof T & "css"]? : never }, filePath?: string): CSSOutput<T>;
 /** Input to globalCss(): selector → property-value map. */
 type GlobalCSSInput = Record<string, Record<string, string>>;
 /** Output of globalCss(): extracted CSS string. */
@@ -94,34 +98,27 @@ declare function defineTheme(input: ThemeInput): Theme;
 * @returns Compiled CSS and token list.
 */
 declare function compileTheme(theme: Theme): CompiledTheme;
-/**
-* ThemeProvider — Sets `data-theme` attribute for contextual token switching.
-*
-* Creates a wrapper div element with the appropriate `data-theme` attribute
-* so that contextual CSS custom properties (generated by compileTheme) resolve
-* to the correct variant values.
-*
-* Usage:
-* ```ts
-* ThemeProvider({ theme: 'dark', children: [myApp] });
-* ```
-*/
 /** A child node: either a DOM Node or a string (text content). */
 type ThemeChild = Node | string;
 /** Props for ThemeProvider. */
 interface ThemeProviderProps {
 	/** The theme variant name (e.g., 'light', 'dark'). Defaults to 'light'. */
 	theme?: string;
-	/** Child elements to render inside the provider. */
-	children: ThemeChild[];
+	/**
+	* Child elements to render inside the provider.
+	*
+	* Accepts a single child (what TypeScript sees in JSX), an array, or a
+	* thunk (what the compiler produces after wrapping JSX children).
+	*/
+	children: ThemeChild | ThemeChild[] | (() => ThemeChild | ThemeChild[]);
 }
 /**
 * Create a wrapper div with `data-theme` attribute for theme switching.
 *
-* @param props - Theme and children.
-* @returns A div element with `data-theme` set and children appended.
+* Uses __element() directly (instead of jsx()) so the hydration cursor
+* walker can claim the existing SSR node during mount().
 */
-declare function ThemeProvider(props: ThemeProviderProps): HTMLDivElement;
+declare function ThemeProvider({ theme, children }: ThemeProviderProps): HTMLElement;
 /** A record of variant names to their possible values (each value maps to style entries). */
 type VariantDefinitions = Record<string, Record<string, StyleEntry[]>>;
 /** Extract the variant props type from a variant definitions object. */

package/dist/css/public.js

@@ -6,7 +6,11 @@ import {
   globalCss,
   s,
   variants
-} from "../shared/chunk-f1ynwam4.js";
+} from "../shared/chunk-0p5f7gmg.js";
+import"../shared/chunk-ryb49346.js";
+import"../shared/chunk-g4rch80a.js";
+import"../shared/chunk-hrd0mft1.js";
+import"../shared/chunk-prj7nm08.js";
 export {
   variants,
   s,

package/dist/form/public.d.ts

@@ -12,11 +12,36 @@ interface Signal<T> {
 	notify(): void;
 }
 /**
+* A read-only reactive value derived from other signals.
+*/
+interface ReadonlySignal<T> {
+	/** Get the current value and subscribe to changes. */
+	readonly value: T;
+	/** Read the current value without subscribing. */
+	peek(): T;
+}
+interface FieldState<T = unknown> {
+	error: Signal<string | undefined>;
+	dirty: Signal<boolean>;
+	touched: Signal<boolean>;
+	value: Signal<T>;
+	setValue: (value: T) => void;
+	reset: () => void;
+}
+declare function createFieldState<T>(_name: string, initialValue?: T): FieldState<T>;
+import { Result } from "@vertz/fetch";
+/**
 * Minimal schema interface compatible with @vertz/schema.
-* Any object with a `parse(data: unknown): T` method satisfies this.
+* Any object with a `parse(data: unknown): Result` method satisfies this.
 */
 interface FormSchema<T> {
-	parse(data: unknown): T;
+	parse(data: unknown): {
+		ok: true;
+		data: T;
+	} | {
+		ok: false;
+		error: unknown;
+	};
 }
 /** Result of a validation attempt. */
 type ValidationResult<T> = {
@@ -44,56 +69,87 @@ interface SdkMethod<
 	TBody,
 	TResult
 > {
-	(body: TBody): Promise<TResult>;
+	(body: TBody): PromiseLike<Result<TResult, Error>>;
 	url: string;
 	method: string;
+	meta?: {
+		bodySchema?: FormSchema<TBody>;
+	};
 }
-/** Options for creating a form instance. */
-interface FormOptions<TBody> {
-	/** Explicit schema for client-side validation before submission. */
-	schema: FormSchema<TBody>;
+/**
+* An SDK method with embedded schema metadata.
+* Generated by `@vertz/codegen` — carries `.meta.bodySchema` for auto-validation.
+*/
+interface SdkMethodWithMeta<
+	TBody,
+	TResult
+> extends SdkMethod<TBody, TResult> {
+	meta: {
+		bodySchema: FormSchema<TBody>;
+	};
 }
-/** Callbacks for form submission. Both are optional per spec. */
-interface SubmitCallbacks<TResult> {
-	onSuccess?: (result: TResult) => void;
-	onError?: (errors: Record<string, string>) => void;
+/** 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 FieldAccessors<TBody> = { [K in keyof TBody] : FieldState<TBody[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;
+	submit: (formData?: FormData) => Promise<void>;
+	submitting: Signal<boolean>;
+	dirty: ReadonlySignal<boolean>;
+	valid: ReadonlySignal<boolean>;
+	__bindElement: (el: HTMLFormElement) => void;
 }
-/** A form instance bound to an SDK method. */
-interface FormInstance<
+/**
+* A form instance bound to an SDK method.
+* Combines base properties with per-field reactive state via Proxy.
+* If TBody has any key that conflicts with ReservedFormNames, it produces a type error.
+* TResult is used by form() overloads for return type inference.
+*/
+type FormInstance<
+	TBody,
+	_TResult
+> = keyof TBody & ReservedFormNames extends never ? FormBaseProperties<TBody> & FieldAccessors<TBody> : {
+	__error: `Field name conflicts with reserved form property: ${keyof TBody & ReservedFormNames & string}`;
+};
+/** Options for creating a form instance. */
+interface FormOptions<
 	TBody,
 	TResult
 > {
-	/** Returns `{ action, method }` for progressive enhancement in HTML forms. */
-	attrs(): {
-		action: string;
-		method: string;
-	};
-	/** Reactive signal indicating whether a submission is in progress. */
-	submitting: Signal<boolean>;
-	/**
-	* Returns an event handler that extracts FormData, validates, and submits.
-	* Assignable to onSubmit: `onSubmit={userForm.handleSubmit({ onSuccess })}`.
-	*
-	* Can also be called directly with FormData for non-DOM usage:
-	* `userForm.handleSubmit({ onSuccess })(formData)`.
-	*/
-	handleSubmit(callbacks?: SubmitCallbacks<TResult>): (formDataOrEvent: FormData | Event) => Promise<void>;
-	/** Returns the error message for a field reactively, or undefined if no error. Type-safe field names. */
-	error(field: keyof TBody & string): string | undefined;
+	/** Explicit schema for client-side validation before submission. */
+	schema?: FormSchema<TBody>;
+	/** Initial values for form fields. */
+	initial?: Partial<TBody> | (() => Partial<TBody>);
+	/** Callback invoked after a successful submission. */
+	onSuccess?: (result: TResult) => void;
+	/** Callback invoked when validation or submission fails. */
+	onError?: (errors: Record<string, string>) => void;
+	/** When true, reset the form after a successful submission. */
+	resetOnSuccess?: boolean;
 }
 /**
-* Create a form instance bound to an SDK method with schema validation.
+* Create a form instance bound to an SDK method.
 *
-* The form provides:
-* - `attrs()` for progressive enhancement (returns action/method from SDK metadata)
-* - `handleSubmit()` returns an event handler for FormData extraction, validation, and SDK submission
-* - `error()` for reactive field-level error access
-* - `submitting` signal for loading state
+* The form provides direct properties for progressive enhancement (action, method, onSubmit),
+* per-field reactive state via Proxy, and submission handling with validation.
+*
+* When the SDK method has `.meta.bodySchema` (generated by `@vertz/codegen`),
+* the schema option is optional. When the SDK method lacks `.meta`, the schema option is required.
 */
 declare function form<
 	TBody,
 	TResult
->(sdkMethod: SdkMethod<TBody, TResult>, options: FormOptions<TBody>): FormInstance<TBody, TResult>;
+>(sdkMethod: SdkMethodWithMeta<TBody, TResult>, options?: FormOptions<TBody, TResult>): FormInstance<TBody, TResult>;
+declare function form<
+	TBody,
+	TResult
+>(sdkMethod: SdkMethod<TBody, TResult>, options: Required<Pick<FormOptions<TBody, TResult>, "schema">> & FormOptions<TBody, TResult>): FormInstance<TBody, TResult>;
 /** Options for formDataToObject conversion. */
 interface FormDataOptions {
 	/** When true, coerces numeric strings to numbers and "true"/"false" to booleans. */
@@ -108,4 +164,4 @@ interface FormDataOptions {
 *   "true"/"false" become booleans.
 */
 declare function formDataToObject(formData: FormData, options?: FormDataOptions): Record<string, unknown>;
-export { validate, formDataToObject, form, ValidationResult, SubmitCallbacks, SdkMethod, FormSchema, FormOptions, FormInstance, FormDataOptions };
+export { validate, formDataToObject, form, createFieldState, ValidationResult, SdkMethodWithMeta, SdkMethod, FormSchema, FormOptions, FormInstance, FormDataOptions, FieldState };

package/dist/form/public.js

@@ -1,11 +1,13 @@
 import {
+  createFieldState,
   form,
   formDataToObject,
   validate
-} from "../shared/chunk-tsdpgmks.js";
-import"../shared/chunk-pgymxpn1.js";
+} from "../shared/chunk-q6cpe5k7.js";
+import"../shared/chunk-hrd0mft1.js";
 export {
   validate,
   formDataToObject,
-  form
+  form,
+  createFieldState
 };