zuzu-js 0.1.0

package/stdlib/modules/std/gui/dialogue.zzm

@@ -0,0 +1,592 @@
+=encoding utf8
+
+=head1 NAME
+
+std/gui/dialogue - Dialogue helpers.
+
+=head1 SYNOPSIS
+
+  from std/gui/dialogue import *;
+
+  alert("Saved");
+  let ok := confirm("Continue?");
+  let name := prompt("Name:", value: "Ada");
+
+=head1 IMPLEMENTATION SUPPORT
+
+This module is supported by zuzu.pl, zuzu-rust, and zuzu-js on Electron
+and Browser. It is not supported by zuzu-js on Node.
+
+=head1 DESCRIPTION
+
+This module provides convenience dialogue helpers layered on top of the
+regular C<std/gui> widgets.
+
+=head1 EXPORTS
+
+=head2 Functions
+
+=over
+
+=item C<< alert(String message, ... PairList p) >>, C<< alert_window(String message, ... PairList p) >>
+
+Parameters: C<message> is display text and C<p> contains options.
+Returns: C<null> for C<alert> or C<Window> for C<alert_window>. Shows or
+builds an alert dialogue.
+
+=item C<< confirm(String message, ... PairList p) >>, C<< confirm_window(String message, ... PairList p) >>
+
+Parameters: C<message> is display text and C<p> contains options.
+Returns: C<Boolean> for C<confirm> or C<Window> for
+C<confirm_window>. Shows or builds a confirmation dialogue.
+
+=item C<< prompt(String message, ... PairList p) >>, C<< prompt_window(String message, ... PairList p) >>
+
+Parameters: C<message> is prompt text and C<p> contains options such as
+C<value>. Returns: C<String> or C<null> for C<prompt>, or C<Window> for
+C<prompt_window>. Shows or builds a text prompt.
+
+=item C<< file_open(... PairList p) >>, C<< file_save(... PairList p) >>
+
+Parameters: C<p> contains dialogue options. Returns: path value or
+C<null>. Opens a file selection dialogue.
+
+=item C<< directory_open(... PairList p) >>, C<< directory_save(... PairList p) >>
+
+Parameters: C<p> contains dialogue options. Returns: path value or
+C<null>. Opens a directory selection dialogue.
+
+=item C<< colour_picker(... PairList p) >>
+
+Parameters: C<p> contains dialogue options. Returns: C<String> or
+C<null>. Opens a colour picker and returns a normalized colour string.
+
+=item C<< file_open_window(... PairList p) >>, C<< file_save_window(... PairList p) >>, C<< directory_open_window(... PairList p) >>, C<< directory_save_window(... PairList p) >>, C<< colour_picker_window(... PairList p) >>
+
+Parameters: C<p> contains dialogue options. Returns: C<Window>. Builds
+the corresponding GUI dialogue window.
+
+=back
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< std/gui/dialogue >> is copyright Toby Inkster.
+
+It is free software; you may redistribute it and/or modify it under
+the terms of either the Artistic License 1.0 or the GNU General Public
+License version 2.
+
+=cut
+
+from std/gui try import
+	EM,
+	Window,
+	VBox,
+	HBox,
+	Label,
+	Text,
+	Input,
+	Button,
+	Widget,
+	native_file_open,
+	native_file_save,
+	native_directory_open,
+	native_directory_save,
+	native_colour_picker;
+from std/gui/objects try import
+	meta as _objects_meta,
+	native_alert,
+	native_confirm,
+	native_prompt;
+from std/colour import parse_colour;
+from std/string import split;
+from std/tui import
+	colour_text,
+	directory_completions,
+	filename_completions,
+	readline;
+
+function _tui_string ( value ) {
+	return value ≡ null ? "" : "" _ value;
+}
+
+function _gui_backend () {
+	if ( _objects_meta ≢ null ) {
+		return _objects_meta{backend};
+	}
+	return "";
+}
+
+function _path_dialogue_unsupported () {
+	if ( __system__{deny_fs} ) {
+		die "GUI_DIALOGUE_FS_DENIED: file and directory dialogues require filesystem capability";
+	}
+	if ( _gui_backend() eq "browser-dom" ) {
+		die "GUI_DIALOGUE_UNSUPPORTED: file and directory dialogues are unsupported in JS/Browser";
+	}
+}
+
+function _tui_prompt ( String message, PairList p, String default_value ) {
+	return readline(
+		colour_text( message _ " ", "cyan" ),
+		default_value,
+		null,
+	);
+}
+
+function _tui_path_dialog (
+	String label,
+	String default_value,
+	completion,
+	PairList p
+) {
+	let answer := readline(
+		colour_text( p.get( "label", label ) _ " ", "cyan" ),
+		_tui_string( p.get( "value", default_value ) ),
+		completion,
+	);
+	if ( p.get( "multiple", false ) ) {
+		return split( answer, p.get( "separator", "\n" ) );
+	}
+	return answer;
+}
+
+function _parse_colour_or_null ( value ) {
+	return try {
+		parse_colour( _tui_string(value) );
+	}
+	catch {
+		null;
+	};
+}
+
+function _colour_initial_value ( PairList p ) {
+	let raw := _tui_string( p.get( "value", "#000000" ) );
+	let parsed := _parse_colour_or_null(raw);
+	return parsed ≢ null ? parsed : raw;
+}
+
+function _colour_default_value ( PairList p ) {
+	return _parse_colour_or_null( p.get( "value", "#000000" ) ) ?: "#000000";
+}
+
+function _tui_colour_dialog ( PairList p ) {
+	let default_value := _colour_default_value(p);
+	while ( true ) {
+		let answer := readline(
+			colour_text( p.get( "label", "Colour:" ) _ " ", "cyan" ),
+			default_value,
+			null,
+		);
+		let parsed := _parse_colour_or_null(answer);
+		if ( parsed ≢ null ) {
+			return parsed;
+		}
+		say( colour_text( "Invalid colour; try #336699 or red.", "yellow" ) );
+	}
+}
+
+function _dialogue_window (
+	String kind,
+	String title,
+	Widget body,
+	Array buttons,
+	PairList p
+) {
+	let button_row := HBox(
+		id: "buttons",
+		align: "right",
+		gap: 6,
+		height: p.get( "button_row_height", 2.125 × EM ),
+		maxheight: p.get( "button_row_height", 2.125 × EM ),
+	);
+	for ( let button in buttons ) {
+		button_row.add_child(button);
+	}
+	let w := Window(
+		title: title,
+		width: p.get( "width", 360 ),
+		height: p.get( "height", 180 ),
+		resizable: p.get( "resizable", false ),
+		modal: true,
+		VBox(
+			id: p.get( "id", null ),
+			gap: p.get( "gap", 8 ),
+			padding: p.get( "padding", 12 ),
+			body,
+			button_row,
+		),
+	);
+	w.meta( "dialogue.kind", kind );
+	return w;
+}
+
+function _message_body ( String message, PairList p ) {
+	return Text(
+		id: p.get( "message_id", "message" ),
+		value: message,
+		readonly: true,
+		wrap: true,
+	);
+}
+
+function _primary_button ( PairList p, String fallback ) {
+	return Button(
+		id: p.get( "ok_id", "ok" ),
+		text: p.get( "ok_text", fallback ),
+		variant: "primary",
+		width: p.get( "button_width", 5.5 × EM ),
+		height: p.get( "button_height", 1.75 × EM ),
+		maxheight: p.get( "button_height", 1.75 × EM ),
+	);
+}
+
+function _cancel_button ( PairList p ) {
+	return Button(
+		id: p.get( "cancel_id", "cancel" ),
+		text: p.get( "cancel_text", "Cancel" ),
+		width: p.get( "button_width", 5.5 × EM ),
+		height: p.get( "button_height", 1.75 × EM ),
+		maxheight: p.get( "button_height", 1.75 × EM ),
+	);
+}
+
+function _alert_window ( String message, PairList p ) {
+	let ok := _primary_button( p, "OK" );
+	let w := _dialogue_window(
+		"alert",
+		p.get( "title", "Alert" ),
+		_message_body( message, p ),
+		[ ok ],
+		p,
+	);
+	ok.click( function () {
+		w.close(null);
+	} );
+	return w;
+}
+
+function alert_window ( String message, ... PairList p ) {
+	return _alert_window( message, p );
+}
+
+function alert ( String message, ... PairList p ) {
+	if ( p.has("auto_result") ) {
+		return null;
+	}
+	if ( __system__{deny_gui} ) {
+		say( colour_text( message, "yellow" ) );
+		return null;
+	}
+	if ( native_alert ≢ null ) {
+		let native_result := native_alert( message, p );
+		if ( native_result ) {
+			return null;
+		}
+	}
+	return _alert_window( message, p ).call();
+}
+
+function _confirm_window ( String message, PairList p ) {
+	let ok := _primary_button( p, p.get( "ok_text", "OK" ) );
+	let cancel := _cancel_button(p);
+	let w := _dialogue_window(
+		"confirm",
+		p.get( "title", "Confirm" ),
+		_message_body( message, p ),
+		[ cancel, ok ],
+		p,
+	);
+	ok.click( function () {
+		w.close(true);
+	} );
+	cancel.click( function () {
+		w.close(false);
+	} );
+	return w;
+}
+
+function confirm_window ( String message, ... PairList p ) {
+	return _confirm_window( message, p );
+}
+
+function confirm ( String message, ... PairList p ) {
+	if ( p.has("auto_result") ) {
+		return p.get("auto_result") ? true : false;
+	}
+	if ( __system__{deny_gui} ) {
+		let yes_default := p.get( "value", p.get( "default", false ) );
+		let suffix := yes_default ? " [Y/n] " : " [y/N] ";
+		let answer := readline(
+			colour_text( message _ suffix, "cyan" ),
+			yes_default ? "y" : "n",
+			null,
+		);
+		return ( answer ~ /^(?:y|yes|1|true)$/i ) ? true : false;
+	}
+	if ( native_confirm ≢ null ) {
+		let native_result := native_confirm( message, p );
+		if ( native_result ≢ null ) {
+			return native_result ? true : false;
+		}
+	}
+	return _confirm_window( message, p ).call() ? true : false;
+}
+
+function _prompt_window ( String message, PairList p ) {
+	let input := Input(
+		id: p.get( "input_id", "value" ),
+		value: p.get( "value", "" ),
+		placeholder: p.get( "placeholder", "" ),
+	);
+	let ok := _primary_button( p, p.get( "ok_text", "OK" ) );
+	let cancel := _cancel_button(p);
+	let w := _dialogue_window(
+		"prompt",
+		p.get( "title", "Prompt" ),
+		VBox(
+			gap: 6,
+			_message_body( message, p ),
+			input,
+		),
+		[ cancel, ok ],
+		p,
+	);
+	ok.click( function () {
+		w.close( input.value() );
+	} );
+	cancel.click( function () {
+		w.close(null);
+	} );
+	return w;
+}
+
+function prompt_window ( String message, ... PairList p ) {
+	return _prompt_window( message, p );
+}
+
+function prompt ( String message, ... PairList p ) {
+	if ( p.has("auto_result") ) {
+		return p.get("auto_result");
+	}
+	if ( __system__{deny_gui} ) {
+		return _tui_prompt(
+			message,
+			p,
+			_tui_string( p.get( "value", "" ) ),
+		);
+	}
+	if ( native_prompt ≢ null ) {
+		let native_result := native_prompt( message, p );
+		if ( _gui_backend() eq "browser-dom" ) {
+			return native_result;
+		}
+		if ( native_result ≢ null ) {
+			return native_result;
+		}
+	}
+	return _prompt_window( message, p ).call();
+}
+
+function _path_dialog_window (
+	String kind,
+	String title,
+	String label,
+	String default_value,
+	PairList p
+) {
+	let input := Input(
+		id: p.get( "input_id", "path" ),
+		value: p.get( "value", default_value ),
+		placeholder: p.get( "placeholder", "" ),
+		multiline: p.get( "multiple", false ),
+	);
+	let ok := _primary_button( p, p.get( "ok_text", "OK" ) );
+	let cancel := _cancel_button(p);
+	let w := _dialogue_window(
+		kind,
+		p.get( "title", title ),
+		VBox(
+			gap: 6,
+			Label( text: p.get( "label", label ), ("for"): input.id() ),
+			input,
+		),
+		[ cancel, ok ],
+		p,
+	);
+	ok.click( function () {
+		if ( p.get( "multiple", false ) ) {
+			w.close( split( input.value(), p.get( "separator", "\n" ) ) );
+		}
+		else {
+			w.close( input.value() );
+		}
+	} );
+	cancel.click( function () {
+		w.close(null);
+	} );
+	return w;
+}
+
+function file_open_window ( ... PairList p ) {
+	return _path_dialog_window( "file_open", "Open File", "File:", "", p );
+}
+
+function file_save_window ( ... PairList p ) {
+	return _path_dialog_window( "file_save", "Save File", "File:", "", p );
+}
+
+function directory_open_window ( ... PairList p ) {
+	return _path_dialog_window(
+		"directory_open",
+		"Open Directory",
+		"Directory:",
+		"",
+		p,
+	);
+}
+
+function directory_save_window ( ... PairList p ) {
+	return _path_dialog_window(
+		"directory_save",
+		"Save Directory",
+		"Directory:",
+		"",
+		p,
+	);
+}
+
+function _colour_picker_window ( PairList p ) {
+	let input := Input(
+		id: p.get( "input_id", "path" ),
+		value: _colour_initial_value(p),
+		placeholder: p.get( "placeholder", "#336699" ),
+	);
+	let ok := _primary_button( p, p.get( "ok_text", "OK" ) );
+	let cancel := _cancel_button(p);
+	let default_value := _colour_default_value(p);
+	let sync_ok := function () {
+		ok.set_enabled( _parse_colour_or_null( input.value() ) ≢ null );
+	};
+	let w := _dialogue_window(
+		"colour_picker",
+		p.get( "title", "Choose Colour" ),
+		VBox(
+			gap: 6,
+			Label(
+				text: p.get( "label", "Colour:" ),
+				("for"): input.id(),
+			),
+			input,
+		),
+		[ cancel, ok ],
+		p,
+	);
+	sync_ok();
+	input.on( "change", sync_ok );
+	ok.click( function () {
+		let parsed := _parse_colour_or_null( input.value() );
+		if ( parsed ≢ null ) {
+			w.close(parsed);
+		}
+	} );
+	cancel.click( function () {
+		w.close(default_value);
+	} );
+	return w;
+}
+
+function colour_picker_window ( ... PairList p ) {
+	return _colour_picker_window(p);
+}
+
+function file_open ( ... PairList p ) {
+	_path_dialogue_unsupported();
+	if ( p.has("auto_result") ) {
+		return p.get("auto_result");
+	}
+	if ( __system__{deny_gui} ) {
+		return _tui_path_dialog( "File:", "", filename_completions, p );
+	}
+	return native_file_open(p);
+}
+
+function file_save ( ... PairList p ) {
+	_path_dialogue_unsupported();
+	if ( p.has("auto_result") ) {
+		return p.get("auto_result");
+	}
+	if ( __system__{deny_gui} ) {
+		return _tui_path_dialog( "File:", "", filename_completions, p );
+	}
+	return native_file_save(p);
+}
+
+function directory_open ( ... PairList p ) {
+	_path_dialogue_unsupported();
+	if ( p.has("auto_result") ) {
+		return p.get("auto_result");
+	}
+	if ( __system__{deny_gui} ) {
+		return _tui_path_dialog(
+			"Directory:",
+			"",
+			directory_completions,
+			p,
+		);
+	}
+	return native_directory_open(p);
+}
+
+function directory_save ( ... PairList p ) {
+	_path_dialogue_unsupported();
+	if ( p.has("auto_result") ) {
+		return p.get("auto_result");
+	}
+	if ( __system__{deny_gui} ) {
+		return _tui_path_dialog(
+			"Directory:",
+			"",
+			directory_completions,
+			p,
+		);
+	}
+	if ( native_directory_save ≢ null ) {
+		let native_result := native_directory_save(p);
+		if ( native_result ≢ null ) {
+			return native_result;
+		}
+		if ( _gui_backend() eq "electron-dom" ) {
+			return null;
+		}
+	}
+	return _path_dialog_window(
+		"directory_save",
+		"Save Directory",
+		"Directory:",
+		"",
+		p,
+	).call();
+}
+
+function colour_picker ( ... PairList p ) {
+	if ( p.has("auto_result") ) {
+		return parse_colour( _tui_string( p.get("auto_result") ) );
+	}
+	if ( __system__{deny_gui} ) {
+		return _tui_colour_dialog(p);
+	}
+	if ( native_colour_picker ≢ null ) {
+		let native_result := native_colour_picker(p);
+		if ( native_result ≢ null ) {
+			return parse_colour(native_result);
+		}
+		if ( _gui_backend() eq "browser-dom" ) {
+			return null;
+		}
+	}
+	if ( _gui_backend() eq "electron-dom" ) {
+		return _colour_picker_window(p).call();
+	}
+	return parse_colour( _colour_picker_window(p).call() );
+}

package/stdlib/modules/std/gui/objects.zzm

@@ -0,0 +1,123 @@
+=encoding utf8
+
+=head1 NAME
+
+std/gui/objects - Runtime-supported GUI object classes.
+
+=head1 SYNOPSIS
+
+  from std/gui/objects import Window, VBox, Button;
+
+  let w := new Window( title: "Demo" );
+  let b := new Button( text: "OK", id: "submit" );
+  w.set_content( new VBox( children: [ b ] ) );
+
+=head1 IMPLEMENTATION SUPPORT
+
+This module is supported by zuzu.pl, zuzu-rust, and zuzu-js on Electron.
+It is not supported by zuzu-js on Node or Browser.
+
+=head1 DESCRIPTION
+
+This runtime-supported module provides the C<std/gui> object model.
+Host runtimes provide visible windows and baseline controls where GUI
+support is available, while retaining the same object tree and event API
+for tests and future backends.
+
+=head1 EXPORTS
+
+=head2 Variables
+
+=over
+
+=item C<meta>
+
+Type: C<Dict>. Runtime/backend metadata. Current keys include
+C<backend>, C<font_size_pixels>, C<font_name>, and C<font_point_size>.
+
+=back
+
+=head2 Classes
+
+=over
+
+=item C<Widget>
+
+Base class for GUI objects. Supports C<id>, C<parent>, C<children>,
+C<add_child>, C<remove_child>, C<enabled>, C<set_enabled>,
+C<visible>, C<set_visible>, C<width>, C<height>, C<minwidth>,
+C<minheight>, C<maxwidth>, C<maxheight>, C<classes>, C<add_class>,
+C<remove_class>, C<style>, C<meta>, C<find_by_id>, C<on>, C<once>,
+C<off>, C<emit>, and event shortcuts such as C<click>.
+
+Common widget methods take or return widget state values. Getters return
+the current value; setters return the widget so calls can be chained.
+
+=item C<Window>
+
+Top-level container with C<show>, C<call>, C<close>, C<content>, and
+C<set_content>. In Phase 1, C<show> is non-rendering and C<call>
+returns the current close result.
+
+=item C<VBox>, C<HBox>, C<Frame>
+
+Layout containers.
+
+=item C<Menu>, C<MenuItem>
+
+Window menu bar widgets. C<Menu> widgets are direct C<Window> children;
+C<MenuItem> widgets are direct C<Menu> children.
+
+=item C<Label>, C<Text>, C<RichText>, C<Image>
+
+Content widgets.
+
+=item C<Input>, C<DatePicker>, C<Checkbox>, C<Radio>, C<RadioGroup>,
+C<Select>, C<Button>
+
+Baseline input widgets.
+
+=item C<Separator>, C<Slider>, C<Progress>
+
+Extended baseline controls.
+
+=item C<Tabs>, C<Tab>
+
+Tab container and tab pages. C<Tabs.selected> selects the active C<Tab>.
+
+=item C<ListView>, C<TreeView>
+
+Collection controls with selection and activation events.
+
+=item C<Event>
+
+Event object passed to handlers which accept an argument. Provides
+C<name>, C<target>, C<current_target>, C<window>, C<phase>,
+C<timestamp>, C<data>, C<cancelled>, C<default_prevented>,
+C<stop_propagation>, and C<prevent_default>.
+
+=item C<ListenerToken>
+
+Opaque token returned by C<on> and C<once>, accepted by C<off>.
+
+=item C<native_file_open>, C<native_file_save>, C<native_directory_open>,
+C<native_directory_save>, C<native_alert>, C<native_confirm>,
+C<native_prompt>, C<native_colour_picker>
+
+Backend-native modal file and directory dialogue hooks used by
+C<std/gui/dialogue>. These return selected paths or C<null> when cancelled.
+C<native_alert>, C<native_confirm>, C<native_prompt>, and
+C<native_colour_picker> return C<null> when unsupported so
+C<std/gui/dialogue> can use its shared fallback.
+
+=back
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< std/gui/objects >> is copyright Toby Inkster.
+
+It is free software; you may redistribute it and/or modify it under
+the terms of either the Artistic License 1.0 or the GNU General Public
+License version 2.
+
+=cut