nuclo 0.2.6 → 0.2.9

package/types/features/style.d.ts

@@ -11,16 +11,26 @@
 //
 // The themeless defaults (css, cx, keyframes, globalStyle) are registered as
 // globals by the runtime bootstrap; themed instances come from createCss().
+//
+// The type definitions live in types/style.d.ts (NOT src/) so they resolve in
+// the published package, which ships only dist/ and types/.
 
 import type {
 	ClassInput as NucloClassInput,
+	CssInstance as NucloCssInstance,
 	CSSProperties as NucloCSSProperties,
 	FlatStyle as NucloFlatStyle,
+	KeyframeFrames as NucloKeyframeFrames,
+	KeyframeStop as NucloKeyframeStop,
 	Size as NucloSize,
 	Style as NucloStyle,
 	StyleResult as NucloStyleResult,
 	ThemeConfig as NucloThemeConfig,
-} from "../../src/style/css";
+	VariantDefinitions as NucloVariantDefinitions,
+	VariantProps as NucloVariantProps,
+	VariantsConfig as NucloVariantsConfig,
+	VariantsFn as NucloVariantsFn,
+} from "../style";
 
 declare global {
 	export type Size = NucloSize;
@@ -30,26 +40,18 @@ declare global {
 	export type Style<T extends ThemeConfig = ThemeConfig> = NucloStyle<T>;
 	export type StyleResult = NucloStyleResult;
 	export type ClassInput = NucloClassInput;
+	export type KeyframeStop = NucloKeyframeStop;
+	export type KeyframeFrames<T extends ThemeConfig = ThemeConfig> = NucloKeyframeFrames<T>;
+	export type VariantDefinitions<T extends ThemeConfig = ThemeConfig> = NucloVariantDefinitions<T>;
+	export type VariantProps<V extends VariantDefinitions> = NucloVariantProps<V>;
+	export type VariantsConfig<T extends ThemeConfig, V extends VariantDefinitions<T>> = NucloVariantsConfig<T, V>;
+	export type VariantsFn<V extends VariantDefinitions> = NucloVariantsFn<V>;
 
-	export interface CssInstance<T extends ThemeConfig = ThemeConfig> {
-		/**
-		 * Compile a style object into atomic CSS classes.
-		 * Returns `{ className }` — usable directly as a nuclo attributes object.
-		 */
-		css(style: Style<T>): StyleResult;
-		/**
-		 * Compose class lists with exact conflict resolution: when two inputs
-		 * style the same (query, selector, property), the last one wins.
-		 * Accepts results, raw class strings, and falsy values for conditionals.
-		 */
-		cx(...inputs: ClassInput[]): StyleResult;
-		/** Register a @keyframes block; returns its generated animation name. */
-		keyframes(frames: Record<string, FlatStyle<T>>): string;
-		/** Global selector styles (body, resets). Flat properties only. */
-		globalStyle(selector: string, style: FlatStyle<T>): void;
-		/** The theme this instance was created with. */
-		theme: T;
-	}
+	/**
+	 * A themed styling instance: css/cx/variants/keyframes/globalStyle bound to
+	 * a theme. Returned by createCss().
+	 */
+	export type CssInstance<T extends ThemeConfig = ThemeConfig> = NucloCssInstance<T>;
 
 	/**
 	 * Create a themed styling instance. Theme tokens (colors, fonts, shadows,
@@ -62,8 +64,12 @@ declare global {
 	function css(style: Style<object>): StyleResult;
 	/** Compose class lists with last-wins conflict resolution. */
 	function cx(...inputs: ClassInput[]): StyleResult;
+	/** Themeless variants() recipe helper. */
+	function variants<const V extends VariantDefinitions<object>>(
+		config: VariantsConfig<object, V>,
+	): VariantsFn<V>;
 	/** Themeless keyframes() helper. */
-	function keyframes(frames: Record<string, FlatStyle<object>>): string;
+	function keyframes(frames: KeyframeFrames<object>): string;
 	/** Themeless globalStyle() helper. */
 	function globalStyle(selector: string, style: FlatStyle<object>): void;
 }

package/types/index.d.ts

@@ -11,7 +11,69 @@ import "./features/on";
 import "./features/render";
 import "./features/style";
 
-// Re-export on() helper for module-style consumers (import { on } from "nuclo")
+// ---------------------------------------------------------------------------
+// Module export surface — mirrors the runtime exports of src/index.ts so that
+// module-style consumers (import { render } from "nuclo") get the same types
+// as global-style consumers (import "nuclo"). Keep in sync with src/index.ts.
+// ---------------------------------------------------------------------------
+
+// Runtime bootstrap / tag registry
+export function initializeRuntime(): void;
+export function registerGlobalTagBuilders(target?: Record<string, unknown>): void;
+export const HTML_TAGS: ReadonlyArray<ElementTagName>;
+export const SVG_TAGS: ReadonlyArray<SVGTagName>;
+export const SELF_CLOSING_TAGS: ReadonlyArray<ElementTagName>;
+export function createHtmlTagBuilder<TTagName extends ElementTagName>(
+  tagName: TTagName,
+): ExpandedElementBuilder<TTagName>;
+export function createSvgTagBuilder<TTagName extends SVGTagName>(
+  tagName: TTagName,
+): ExpandedSVGElementBuilder<TTagName>;
+
+// Modifier application
+export function applyNodeModifier<TTagName extends ElementTagName>(
+  parent: ExpandedElement<TTagName>,
+  modifier: NodeModLike<TTagName>,
+  index: number,
+): Node | null;
+export function applyAttributes<TTagName extends ElementTagName>(
+  element: ExpandedElement<TTagName>,
+  attributes: ExpandedElementAttributes<TTagName>,
+  mergeClassName?: boolean,
+): void;
+export function createHtmlElementWithModifiers<TTagName extends ElementTagName>(
+  tagName: TTagName,
+  modifiers: ReadonlyArray<NodeModLike<TTagName>>,
+): ExpandedElement<TTagName>;
+export function createSvgElementWithModifiers<TTagName extends SVGTagName>(
+  tagName: TTagName,
+  modifiers: ReadonlyArray<SVGElementModifierLike<TTagName>>,
+): SVGElementTagNameMap[TTagName];
+
+// Core primitives (same signatures as the globals)
+export function list<T, TTagName extends ElementTagName = ElementTagName>(
+  itemsProvider: ListItemsProvider<T>,
+  render: ListRenderFunction<T, TTagName>,
+): ListModifier<TTagName>;
+export function when<TTagName extends ElementTagName = ElementTagName>(
+  condition: WhenCondition,
+  ...content: WhenContent<TTagName>[]
+): WhenBuilder<TTagName>;
+export function update(...scopeIds: string[]): void;
+export function scope<TTagName extends ElementTagName = ElementTagName>(
+  ...ids: string[]
+): NodeModFn<TTagName>;
+export function render<TTagName extends ElementTagName = ElementTagName>(
+  nodeModFn: NodeModFn<TTagName>,
+  parent?: Element,
+  index?: number,
+): ExpandedElement<TTagName>;
+export function hydrate<TTagName extends ElementTagName = ElementTagName>(
+  nodeModFn: NodeModFn<TTagName>,
+  parent?: Element,
+): ExpandedElement<TTagName>;
+
+// on() helper (same overloads as the global)
 export function on<K extends keyof HTMLElementEventMap, TTagName extends ElementTagName = ElementTagName>(
   type: K,
   listener: TypedEventListener<HTMLElementTagNameMap[TTagName], HTMLElementEventMap[K]>,
@@ -23,4 +85,53 @@ export function on<K extends string, E extends Event = Event, TTagName extends E
   options?: boolean | AddEventListenerOptions
 ): NodeModFn<TTagName>;
 
-export {};
+// DOM helpers
+export function appendChildren(
+  parent: Element | Node,
+  ...children: Array<Element | Node | string | null | undefined>
+): Element | Node;
+export function createComment(text: string): Comment | null;
+export function createConditionalComment(tagName: string, suffix?: string): Comment | null;
+export function replaceNodeSafely(oldNode: Node, newNode: Node): boolean;
+
+// Type guards / environment
+export function isBoolean(value: unknown): value is boolean;
+export function isFunction(value: unknown): value is (...args: unknown[]) => unknown;
+export function isNode<T>(value: T): value is T & Node;
+export function isObject(value: unknown): value is object;
+export function isPrimitive(value: unknown): value is Primitive;
+export function isTagLike<T>(value: T): value is T & { tagName?: string };
+export function isZeroArityFunction(value: unknown): value is () => unknown;
+export const isBrowser: boolean;
+
+// Styling (themeless default instance + themed factory)
+export function createCss<const T extends ThemeConfig>(theme?: T): CssInstance<T>;
+export function css(style: Style<object>): StyleResult;
+export function cx(...inputs: ClassInput[]): StyleResult;
+export function variants<const V extends VariantDefinitions<object>>(
+  config: VariantsConfig<object, V>,
+): VariantsFn<V>;
+export function keyframes(frames: KeyframeFrames<object>): string;
+export function globalStyle(selector: string, style: FlatStyle<object>): void;
+export function getCssText(): string;
+export function resetStyles(): void;
+export function setSSRCollector(fn: ((rule: string) => void) | null): void;
+
+// Styling types (same names as the globals, importable as module types)
+export type {
+  ClassInput,
+  CssInstance,
+  CSSProperties,
+  FlatStyle,
+  KeyframeFrames,
+  KeyframeStop,
+  Pseudo,
+  Size,
+  Style,
+  StyleResult,
+  ThemeConfig,
+  VariantDefinitions,
+  VariantProps,
+  VariantsConfig,
+  VariantsFn,
+} from "./style";

package/types/polyfill.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Type declarations for the `nuclo/polyfill` subpath.
+ *
+ * Hand-written (mirroring src/polyfill/index.ts) and shipped from `types/` so
+ * the subpath stays typed even when `dist/` holds only watch-mode JS bundles —
+ * `tsdown --watch` cleans dist and emits no declarations. Keep in sync with
+ * src/polyfill/*.
+ *
+ * The primary use is the side-effect import (`import "nuclo/polyfill"`), which
+ * installs document/Event/Node/Element/HTMLElement on globalThis when they are
+ * missing (Node.js SSR). The named exports below expose the polyfill classes.
+ */
+
+// Load the ambient nuclo globals (ExpandedElement, ElementTagName, …).
+import "./index";
+
+/** Minimal Node base used for instanceof checks in the Node.js polyfill. */
+export class NucloNode {
+	nodeType: number;
+	nodeName: string;
+	nodeValue: string | null;
+	parentNode: unknown;
+	textContent: string;
+	get childNodes(): NodeListOf<ChildNode>;
+}
+
+/** Text node polyfill. */
+export class NucloText {
+	nodeType: number;
+	nodeName: string;
+	data: string;
+	textContent: string;
+	parentNode: unknown;
+	nodeValue: string;
+	constructor(data: string);
+}
+
+/** Element polyfill: the subset of the DOM Element surface nuclo SSR uses. */
+export class NucloElement extends NucloNode {
+	tagName: string;
+	children: unknown[];
+	className: string;
+	id: string;
+	namespaceURI?: string;
+	sheet?: CSSStyleSheet | null;
+	rawMods?: unknown[];
+	mods?: unknown[];
+	attributes: Map<string, string>;
+	style: CSSStyleDeclaration;
+	classList: DOMTokenList;
+	innerHTML: string;
+	constructor(tagName: string);
+	appendChild<T extends Node>(child: T): T;
+	insertBefore<T extends Node>(newNode: T, referenceNode: Node | null): T;
+	removeChild<T extends Node>(child: T): T;
+	replaceChild<T extends Node>(newChild: Node, oldChild: T): T;
+	setAttribute(name: string, value: string): void;
+	getAttribute(name: string): string | null;
+	removeAttribute(name: string): void;
+	hasAttribute(name: string): boolean;
+	addEventListener(type: string, listener: EventListener): void;
+	removeEventListener(type: string, listener: EventListener): void;
+	dispatchEvent(event: Event): boolean;
+	querySelector(selector: string): Element | null;
+	querySelectorAll(selector: string): NodeListOf<Element>;
+}
+
+/** Document polyfill backing `document` in Node.js. */
+export class NucloDocument {
+	head: ExpandedElement;
+	body: ExpandedElement;
+	createElement(tagName: string, options?: unknown): ExpandedElement;
+	createElementNS(namespace: string, tagName: string, options?: unknown): ExpandedElement;
+	createTextNode(data: string): Text;
+	createComment(data: string): Comment;
+	createDocumentFragment(): DocumentFragment;
+	querySelector(selector: string): Element | null;
+	querySelectorAll(selector: string): NodeListOf<Element>;
+	addEventListener(type: string, listener: EventListener, options?: boolean | AddEventListenerOptions): void;
+	removeEventListener(type: string, listener: EventListener, options?: boolean | AddEventListenerOptions): void;
+	dispatchEvent(event: Event): boolean;
+	contains(node: Node): boolean;
+}
+
+/** Event polyfill (structurally compatible with the DOM Event interface). */
+export class NucloEvent implements Event {
+	type: string;
+	bubbles: boolean;
+	cancelable: boolean;
+	composed: boolean;
+	currentTarget: EventTarget | null;
+	defaultPrevented: boolean;
+	eventPhase: number;
+	isTrusted: boolean;
+	target: EventTarget | null;
+	timeStamp: number;
+	readonly AT_TARGET: 2;
+	readonly BUBBLING_PHASE: 3;
+	readonly CAPTURING_PHASE: 1;
+	readonly NONE: 0;
+	returnValue: boolean;
+	srcElement: EventTarget | null;
+	cancelBubble: boolean;
+	constructor(type: string, eventInitDict?: EventInit);
+	composedPath(): EventTarget[];
+	initEvent(type: string, bubbles?: boolean, cancelable?: boolean): void;
+	preventDefault(): void;
+	stopImmediatePropagation(): void;
+	stopPropagation(): void;
+}
+
+/** CustomEvent polyfill. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export class NucloCustomEvent<T = any> extends NucloEvent implements CustomEvent<T> {
+	detail: T;
+	constructor(type: string, eventInitDict?: CustomEventInit<T>);
+	initCustomEvent(type: string, bubbles?: boolean, cancelable?: boolean, detail?: T): void;
+}
+
+/** The active document: the browser global when present, else the polyfill. */
+export const document: Document | NucloDocument;
+/** The active Event constructor: the browser global when present, else the polyfill. */
+export const Event: typeof globalThis.Event | typeof NucloEvent;
+/** The active CustomEvent constructor: the browser global when present, else the polyfill. */
+export const CustomEvent: typeof globalThis.CustomEvent | typeof NucloCustomEvent;
+/** Alias of NucloNode (installed as globalThis.Node when missing). */
+export const Node: typeof NucloNode;
+/** Alias of NucloElement (installed as globalThis.Element when missing). */
+export const Element: typeof NucloElement;
+/** Alias of NucloElement (installed as globalThis.HTMLElement when missing). */
+export const HTMLElement: typeof NucloElement;

package/types/ssr.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Type declarations for the `nuclo/ssr` subpath.
+ *
+ * Hand-written (mirroring src/ssr/index.ts) and shipped from `types/` so the
+ * subpath stays typed even when `dist/` holds only watch-mode JS bundles —
+ * `tsdown --watch` cleans dist and emits no declarations. Keep in sync with
+ * src/ssr/index.ts.
+ */
+
+// Load the ambient nuclo globals (NodeModFn, ElementTagName, tag builders, …)
+// so SSR-only consumers get them without importing the main entry.
+import "./index";
+
+/** Anything renderToString accepts: a component factory, a DOM node, or nothing. */
+export type RenderableInput =
+  | NodeModFn<ElementTagName>
+  | Element
+  | Node
+  | null
+  | undefined;
+
+/**
+ * Renders a Nuclo component (or DOM node) to an HTML string.
+ * Text children keep their `<!-- text-N -->` markers so the output is hydratable.
+ */
+export function renderToString(input: RenderableInput): string;
+
+/** Renders multiple Nuclo components to HTML strings. */
+export function renderManyToString(inputs: RenderableInput[]): string[];
+
+/** Renders a Nuclo component wrapped in a container element. */
+export function renderToStringWithContainer(
+  input: RenderableInput,
+  containerTag?: string,
+  containerAttrs?: Record<string, string>,
+): string;
+
+/**
+ * Install a hook receiving every newly minted CSS rule (wrapped in its
+ * at-rule, if any). Installed once at server startup; pass null to remove.
+ */
+export function setSSRCollector(fn: ((rule: string) => void) | null): void;
+
+/** Serialize every registered atomic CSS rule (for a <style> tag in SSR output). */
+export function getCssText(): string;