ripple 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # ripple
 
+## 0.4.1
+
+### Patch Changes
+
+- [#1477](https://github.com/Ripple-TS/ripple/pull/1477)
+  [`670d669`](https://github.com/Ripple-TS/ripple/commit/670d66916a0b2d58254adb3248abc9d3e816fd8d)
+  Thanks [@leonidaz](https://github.com/leonidaz)! - Use property-specific CSS
+  types for HTML and SVG style objects and export `CSSProperties` from `ripple`
+  and `ripple/jsx-runtime`. Numeric lengths such as `width: 400` now produce a
+  type error; specify units with `width: '400px'` or `width: '24rem'`. Unitless
+  CSS properties, zero lengths, camelCase and kebab-case names, and CSS custom
+  properties remain supported.
+
+  Style properties set to `null` or `undefined` are omitted during server
+  rendering and removed on the client, matching the nullable and optional property
+  types and supporting conditional style values. Ripple does not infer or add CSS
+  units.
+
+  Re-export the `JSX` and `Ripple` namespaces as types from `ripple` so element
+  prop and event types can be imported from the main package. The
+  `ripple/jsx-runtime` exports remain available.
+
+- [#1475](https://github.com/Ripple-TS/ripple/pull/1475)
+  [`e008b3f`](https://github.com/Ripple-TS/ripple/commit/e008b3f933a5a5b54ca8b74ae80aa98b6ddfb82f)
+  Thanks [@leonidaz](https://github.com/leonidaz)! - Show public Tracked, Derived,
+  and WritableDerived type names in value property hovers.
+
 ## 0.4.0
 
 ### Minor Changes

package/package.json

@@ -3,7 +3,7 @@
   "description": "Ripple is an elegant TypeScript UI framework",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "module": "src/runtime/index-client.js",
   "main": "src/runtime/index-client.js",
@@ -77,6 +77,7 @@
   },
   "dependencies": {
     "clsx": "^2.1.1",
+    "csstype": "^3.2.3",
     "devalue": "^5.9.2",
     "esm-env": "^1.2.2",
     "@tsrx/core": "^0.2.0",

package/src/jsx-runtime.d.ts

@@ -7,6 +7,7 @@ import type {
 	TSRXElement,
 } from '#public';
 import type { Nullable } from '@tsrx/core/types/helpers';
+import type * as CSS from 'csstype';
 export type { RefValue } from '#public';
 
 /**
@@ -50,10 +51,18 @@ export function jsxs(
  */
 export function Fragment(props: FragmentProps): TSRXElement;
 
+type NullableStyleProperties<T> = { [Property in keyof T]: T[Property] | null };
+
 /** JSX attributes live under Ripple so editor hovers identify their framework. */
 declare namespace Ripple {
 	type ClassValue = string | import('clsx').ClassArray | import('clsx').ClassDictionary;
 
+	/** Inline CSS styles. Values keep their units; null and undefined remove a property. */
+	interface CSSProperties
+		extends NullableStyleProperties<CSS.Properties>, NullableStyleProperties<CSS.PropertiesHyphen> {
+		[property: `--${string}`]: string | number | null | undefined;
+	}
+
 	type Event<
 		Target extends globalThis.EventTarget,
 		EventType extends globalThis.Event,
@@ -493,7 +502,7 @@ declare namespace Ripple {
 		class?: ClassValue | undefined | null;
 		className?: Nullable<string>;
 		id?: Nullable<string>;
-		style?: Nullable<string> | Record<string, string | number>;
+		style?: Nullable<string> | CSSProperties;
 		title?: Nullable<string>;
 		lang?: Nullable<string>;
 		dir?: 'ltr' | 'rtl' | 'auto';
@@ -627,7 +636,7 @@ declare namespace Ripple {
 		// Styling
 		class?: ClassValue | undefined | null;
 		className?: Nullable<string>;
-		style?: Nullable<string> | Record<string, string | number>;
+		style?: Nullable<string> | CSSProperties;
 
 		// Presentation attributes
 		alignmentBaseline?:
@@ -1405,6 +1414,7 @@ declare namespace Ripple {
 }
 
 export import ClassValue = Ripple.ClassValue;
+export import CSSProperties = Ripple.CSSProperties;
 export import JSX = Ripple.JSX;
 export { Ripple };
 

package/src/runtime/internal/client/render.js

@@ -68,7 +68,7 @@ function get_setters(element) {
 /**
  * @param {Element} element
  * @param {any} value
- * @param {Record<string, string> | undefined} prev
+ * @param {Record<string, string | number | null | undefined> | undefined} prev
  * @returns {void}
  */
 export function set_style(element, value, prev = {}) {
@@ -100,8 +100,8 @@ export function set_attribute(element, attribute, value) {
 
 /**
  * @param {HTMLElement} element
- * @param {Record<string, string | number>} new_styles
- * @param {Record<string, string>} prev
+ * @param {Record<string, string | number | null | undefined>} new_styles
+ * @param {Record<string, string | number | null | undefined>} prev
  */
 function apply_styles(element, new_styles, prev) {
 	const style = element.style;
@@ -109,7 +109,8 @@ function apply_styles(element, new_styles, prev) {
 	// Apply new styles
 	for (const key in new_styles) {
 		const css_prop = normalize_css_property_name(key);
-		const value = String(new_styles[key]);
+		const raw_value = new_styles[key];
+		const value = raw_value == null ? null : String(raw_value);
 
 		if (!(key in prev) || prev[key] !== value) {
 			style.setProperty(css_prop, value);

package/src/runtime/internal/server/index.js

@@ -1610,14 +1610,16 @@ export function attr(name, value, is_boolean = false) {
 }
 
 /**
- * @param {Record<string, string | number>} styles
+ * @param {Record<string, string | number | null | undefined>} styles
  * @returns {string}
  */
 function get_styles(styles) {
 	var result = '';
 	for (const key in styles) {
+		const raw_value = styles[key];
+		if (raw_value == null) continue;
 		const css_prop = normalize_css_property_name(key);
-		const value = String(styles[key]).trim();
+		const value = String(raw_value).trim();
 		result += `${css_prop}: ${value}; `;
 	}
 	return result.trim();

package/tests/client/basic/basic.attributes.test.tsrx

@@ -244,6 +244,43 @@ describe('basic client > attribute rendering', () => {
 		expect(div.style.fontWeight).toBe('bold');
 	});
 
+	it.each([undefined, null])('omits %s styles and removes and restores conditional values', (
+		empty,
+	) => {
+		function Basic() @{
+			const active = track(false);
+			<>
+				<button onClick={() => (active.value = !active.value)}>Toggle</button>
+				<div
+					style={{
+						width: active.value ? '400px' : empty,
+						'--scale': active.value ? 2 : empty,
+						margin: 0,
+						opacity: 0,
+						'--literal': 'undefined',
+						'--literal-null': 'null',
+					}}
+				/>
+			</>
+		}
+
+		render(Basic);
+
+		const button = container.querySelector('button');
+		const div = container.querySelector('div');
+
+		for (const active of [false, true, false, true]) {
+			expect(div.style.width).toBe(active ? '400px' : '');
+			expect(div.style.getPropertyValue('--scale')).toBe(active ? '2' : '');
+			expect(div.style.margin).toBe('0px');
+			expect(div.style.opacity).toBe('0');
+			expect(div.style.getPropertyValue('--literal')).toBe('undefined');
+			expect(div.style.getPropertyValue('--literal-null')).toBe('null');
+			button.click();
+			flushSync();
+		}
+	});
+
 	it('render tracked variable as style attribute', () => {
 		function Basic() @{
 			const style = track({ color: 'red', fontWeight: 'bold' });

package/tests/server/basic.attributes.test.tsrx

@@ -235,6 +235,34 @@ describe('basic server > attribute rendering', () => {
 		expect(div.style.fontWeight).toBe('bold');
 	});
 
+	it.each([undefined, null])('omits %s style values from HTML and SVG attributes', async (
+		empty,
+	) => {
+		function Basic() @{
+			const styles = {
+				width: empty,
+				'--scale': empty,
+				margin: 0,
+				opacity: 0,
+				'--literal': 'undefined',
+				'--literal-null': 'null',
+			};
+			<>
+				<div style={styles} />
+				<svg {...{ style: styles }} />
+			</>
+		}
+
+		const { body } = await render(Basic);
+		const { document } = parseHtml(body);
+
+		for (const element of document.querySelectorAll('div, svg')) {
+			expect(element.getAttribute('style')).toBe(
+				'margin: 0; opacity: 0; --literal: undefined; --literal-null: null;',
+			);
+		}
+	});
+
 	it('render tracked variable as style attribute', async () => {
 		function Basic() @{
 			const style = track({ color: 'red', fontWeight: 'bold' });

package/tests/utils/jsx-runtime-types.test.js

@@ -43,6 +43,68 @@ function create_service(source, automatic) {
 }
 
 describe('Ripple JSX types', () => {
+	it.each([true, false])('checks CSS property values (automatic runtime: %s)', (automatic) => {
+		const source = `
+			import type { CSSProperties, Ripple } from 'ripple';
+			import type { CSSProperties as RuntimeCSSProperties } from 'ripple/jsx-runtime';
+
+			const styles = {
+				width: '24rem', height: '50%', margin: 0, padding: '1em',
+				maxWidth: 'calc(100% - 2rem)', minWidth: 'var(--min-width)',
+				opacity: 0.5, lineHeight: 1.5, zIndex: 2, flexGrow: 1,
+				fontSizeAdjust: 0.5, shapeImageThreshold: 0.5, mathDepth: 2, scale: 1.5,
+				'font-size': '1rem', 'line-height': 1.5, 'border-width': 0,
+				WebkitLineClamp: 2, '-webkit-line-clamp': 2,
+				transitionDuration: '200ms',
+				'--space': '1rem', '--scale': 2,
+			} satisfies CSSProperties;
+			const namespaced: Ripple.CSSProperties = styles;
+			const runtime_styles: RuntimeCSSProperties = styles;
+			const html = <div style={namespaced} />;
+			const svg = <svg style={styles}><circle style={{ strokeWidth: 2, 'fill-opacity': 0.5 }} /></svg>;
+			const zero = <div style={{ width: 0 }} />;
+			const css_text = <div style="width: 400px; opacity: 0.5" />;
+			const absent = <div style={null} />;
+			const omitted = <svg style={undefined} />;
+			const conditional = <div style={{ width: Math.random() ? '400px' : undefined, '--scale': undefined }} />;
+			const nullable = {
+				width: null, 'font-size': null, opacity: null, WebkitLineClamp: null,
+				'-webkit-line-clamp': null, '--scale': null,
+			} satisfies CSSProperties;
+			const nullable_html = <div style={nullable} />;
+			const nullable_svg = <svg style={nullable} />;
+
+			// @ts-expect-error Lengths require explicit units unless the value is zero.
+			const bad_styles = { width: 400 } satisfies CSSProperties;
+			// @ts-expect-error Lengths require explicit units unless the value is zero.
+			const bad_width = <div style={{ width: 400 }} />;
+			// @ts-expect-error Kebab-case lengths use the same rules.
+			const bad_font_size = <div style={{ 'font-size': 16 }} />;
+			// @ts-expect-error SVG style objects also require units for these lengths.
+			const bad_svg = <svg style={{ width: 400 }} />;
+			// @ts-expect-error Vendor-prefixed lengths require units too.
+			const bad_vendor_length = <div style={{ WebkitBorderRadius: 4 }} />;
+			// @ts-expect-error Durations require time units, even for zero.
+			const bad_duration = <div style={{ transitionDuration: 0 }} />;
+			// @ts-expect-error Unknown property names do not bypass CSS checking.
+			const bad_property = <div style={{ widht: '400px' }} />;
+			// @ts-expect-error Custom properties accept strings and numbers, not objects.
+			const bad_custom = <div style={{ '--theme': {} }} />;
+			// @ts-expect-error CSS fallback arrays are not supported by the runtime.
+			const bad_array = <div style={{ display: ['flex', 'block'] }} />;
+		`;
+		const { service, file_name } = create_service(source, automatic);
+		try {
+			expect(
+				service
+					.getSemanticDiagnostics(file_name)
+					.map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')),
+			).toEqual([]);
+		} finally {
+			service.dispose();
+		}
+	});
+
 	it.each([true, false])('qualifies HTML tag hovers (automatic runtime: %s)', (automatic) => {
 		const source = `
 			import 'ripple/jsx-runtime';
@@ -68,7 +130,8 @@ describe('Ripple JSX types', () => {
 
 	it('preserves JSX imports, global types, native events, and DOM refs', () => {
 		const source = `
-			import type { ClassValue, JSX as RuntimeJSX, Ripple } from 'ripple/jsx-runtime';
+			import type { ClassValue, JSX as RuntimeJSX, Ripple as RuntimeRipple } from 'ripple/jsx-runtime';
+			import type { JSX as PublicJSX, Ripple } from 'ripple';
 			import { createRefKey, type RefKey } from 'ripple';
 
 			const ref_key: RefKey = createRefKey();
@@ -81,8 +144,10 @@ describe('Ripple JSX types', () => {
 			};
 			const global_props: JSX.IntrinsicElements['input'] = props;
 			const runtime_props: RuntimeJSX.IntrinsicElements['input'] = global_props;
+			const public_props: PublicJSX.IntrinsicElements['input'] = runtime_props;
+			const runtime_namespace_props: RuntimeRipple.InputHTMLAttributes<HTMLInputElement> = public_props;
 			const classes: ClassValue = ['one', { two: true }];
-			const input = <input {...runtime_props} class={classes} />;
+			const input = <input {...public_props} class={classes} />;
 			const svg = <svg><circle cx={10} ref={(node) => { const circle: SVGCircleElement = node; }} /></svg>;
 			// @ts-expect-error Input values do not accept objects.
 			const bad_value = <input value={{}} />;

package/tests/utils/tracked-types.test.js

@@ -0,0 +1,117 @@
+import ts from 'typescript';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * @param {string} source
+ */
+function create_service(source) {
+	const root = process.cwd();
+	const file_name = `${root}/packages/ripple/tracked-types-test.tsx`;
+	const options = {
+		strict: true,
+		target: ts.ScriptTarget.ESNext,
+		module: ts.ModuleKind.ESNext,
+		moduleResolution: ts.ModuleResolutionKind.Bundler,
+		jsx: ts.JsxEmit.Preserve,
+		jsxImportSource: 'ripple',
+		skipLibCheck: true,
+		types: [],
+		paths: {
+			'#public': [`${root}/packages/ripple/types/index.d.ts`],
+			ripple: [`${root}/packages/ripple/types/index.d.ts`],
+			'ripple/jsx-runtime': [`${root}/packages/ripple/src/jsx-runtime.d.ts`],
+		},
+	};
+	const service = ts.createLanguageService({
+		getCompilationSettings: () => options,
+		getScriptFileNames: () => [file_name],
+		getScriptVersion: () => '0',
+		getScriptSnapshot: (name) => {
+			const text = name === file_name ? source : ts.sys.readFile(name);
+			return text === undefined ? undefined : ts.ScriptSnapshot.fromString(text);
+		},
+		getCurrentDirectory: () => root,
+		getDefaultLibFileName: ts.getDefaultLibFilePath,
+		realpath: ts.sys.realpath,
+		directoryExists: ts.sys.directoryExists,
+		getDirectories: ts.sys.getDirectories,
+		fileExists: (name) => name === file_name || ts.sys.fileExists(name),
+		readFile: (name) => (name === file_name ? source : ts.sys.readFile(name)),
+	});
+	return { service, file_name };
+}
+
+describe('Ripple tracked types', () => {
+	it('shows public names in value property hovers', () => {
+		const source = `
+			import { track } from 'ripple';
+			const count = track(0);
+			const derived = track(() => count.value * 2);
+			const writable = track(() => count.value, undefined, true);
+			count.value;
+			derived.value;
+			writable.value;
+		`;
+		const { service, file_name } = create_service(source);
+		try {
+			expect(service.getSemanticDiagnostics(file_name)).toEqual([]);
+			for (const [name, type] of [
+				['count', 'Tracked'],
+				['derived', 'Derived'],
+				['writable', 'WritableDerived'],
+			]) {
+				const info = service.getQuickInfoAtPosition(
+					file_name,
+					source.lastIndexOf(`${name}.value`) + name.length + 1,
+				);
+				expect(ts.displayPartsToString(info?.displayParts)).toBe(
+					`(property) ${type}<number>.value: number`,
+				);
+			}
+		} finally {
+			service.dispose();
+		}
+	});
+
+	it('preserves writes, read-only views, and tracked component props', () => {
+		const source = `
+			import { track, type Component, type Derived, type Tracked } from 'ripple';
+			const count = track(0);
+			count.value = 1;
+			const tracked: Tracked<number> = track(count);
+			const derived: Derived<number> = tracked;
+			const view = count.readOnly();
+			// @ts-expect-error Read-only views reject writes.
+			view.value = 2;
+			const computed = track(() => count.value * 2);
+			// @ts-expect-error Computed values reject writes.
+			computed.value = 2;
+			const writable = track(() => count.value, undefined, true);
+			writable.value = 2;
+			const with_setter = track(() => count.value, undefined, (next) => next);
+			with_setter.value = 3;
+			// @ts-expect-error Tracked values preserve their value type.
+			count.value = 'wrong';
+			// @ts-expect-error Non-component tracked values are not callable.
+			count({});
+			declare const TrackedComponent: Tracked<Component<{ name: string }>>;
+			declare const DerivedComponent: Derived<Component<{ name: string }>>;
+			const valid = <TrackedComponent name="Ripple" />;
+			const valid_derived = <DerivedComponent name="Ripple" />;
+			// @ts-expect-error Tracked components preserve required props.
+			const missing = <TrackedComponent />;
+			// @ts-expect-error Derived components preserve prop types.
+			const invalid = <DerivedComponent name={123} />;
+		`;
+		const { service, file_name } = create_service(source);
+		try {
+			expect(
+				service
+					.getSemanticDiagnostics(file_name)
+					.map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')),
+			).toEqual([]);
+		} finally {
+			service.dispose();
+		}
+	});
+});

package/types/index.d.ts

@@ -1,4 +1,5 @@
 import type { ExtendedEventOptions } from '@tsrx/core/types';
+export type { CSSProperties, JSX, Ripple } from '../src/jsx-runtime.js';
 export { setTransport } from './transport.js';
 export type { Transport, Transporter } from './transport.js';
 export type { RefValue } from '@tsrx/core/runtime/ref';
@@ -220,8 +221,8 @@ export const TRACKED_UPDATED: unique symbol;
 export const SUSPENSE_PENDING: unique symbol;
 export const SUSPENSE_REJECTED: unique symbol;
 
-// Base Tracked interface - all tracked values have a '#v' property containing the actual value
-interface TrackedBase<V> {
+// A tracked value: `track(0)`. Read and write it through `.value`.
+export interface Tracked<V> extends TrackedCallable<V> {
 	'#v': V;
 	value: V;
 	/**
@@ -236,22 +237,20 @@ interface TrackedBase<V> {
 interface TrackedCallable<V> {
 	(props: V extends Component<infer P> ? P : never): V extends Component ? void : never;
 }
-// A tracked value: `track(0)`. Read and write it through `.value`.
-export type Tracked<V> = TrackedBase<V> & TrackedCallable<V>;
-
 // A computed value: `track(() => ...)`. Its `value` is read-only unless the
 // call opted into writes (see `WritableDerived`). A `Tracked` satisfies it.
-interface DerivedBase<V> {
+export interface Derived<V> extends TrackedCallable<V> {
 	'#v': V;
 	readonly value: V;
 	/** A derived is already read-only: returns itself. */
 	readOnly(): Derived<V>;
 }
-export type Derived<V> = DerivedBase<V> & TrackedCallable<V>;
 // A computed value created with a setter (`track(fn, get, set)`) or with
 // `true` in the setter position: writes land as a temporary value until the
 // next recompute.
-export type WritableDerived<V> = TrackedBase<V> & TrackedCallable<V>;
+export interface WritableDerived<V> extends Tracked<V> {
+	value: V;
+}
 
 // Helper type to infer component type from a function that returns a component
 // If T is a function returning a Component, extract the Component type itself, not the return type (void)

package/tests/client/compiler/__snapshots__/compiler.assignments.test.rsrx.snap

@@ -1,12 +0,0 @@
-// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
-
-exports[`compiler > assignments > compiles tracked values in effect with assignment expression 1`] = `"state.count = lazy.value;"`;
-
-exports[`compiler > assignments > compiles tracked values in effect with update expressions 1`] = `
-"_$_.untrack(() => {
-				state.preIncrement = _$_.update_pre(lazy);
-				state.postIncrement = _$_.update(lazy);
-				state.preDecrement = _$_.update_pre(lazy, -1);
-				state.postDecrement = _$_.update(lazy, -1);
-			});"
-`;

package/tests/client/compiler/__snapshots__/compiler.typescript.test.rsrx.snap

@@ -1,46 +0,0 @@
-// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
-
-exports[`compiler > typescript > compiles TSInstantiationExpression 1`] = `
-"import * as _$_ from 'ripple/internal/client';
-
-function makeBox(value) {
-	return { value };
-}
-
-const makeStringBox = (makeBox);
-const stringBox = makeStringBox('abc');
-const ErrorMap = (Map);
-const errorMap = new ErrorMap();"
-`;
-
-exports[`compiler > typescript > removes class TypeScript syntax from JS output 1`] = `
-"import * as _$_ from 'ripple/internal/client';
-
-class PrintEvent {
-	text;
-
-	constructor(text) {
-		this.text = text;
-	}
-}"
-`;
-
-exports[`compiler > typescript > removes class extends type arguments from JS output 1`] = `
-"import * as _$_ from 'ripple/internal/client';
-
-class StringMap extends Map {
-	constructor() {
-		var __block = _$_.scope();
-
-		super();
-	}
-}"
-`;
-
-exports[`compiler > typescript > removes type assertions from function parameters and leaves default values 1`] = `
-"import * as _$_ from 'ripple/internal/client';
-
-function getString(e = 'test') {
-	return e;
-}"
-`;