pipeworks_mud_mapper.callbacks.file_callbacks

File management callbacks.

This module handles:

• Loading map data when a map is selected from the Workspace table

• New map modal open/close/create

• Save and export functionality

• Status updates

Authoring + Export Workflow

The mapper uses SQLite as the authoring source of truth and exports JSON zone files for the game server:

• SQLite maps: Authoring source with coordinates

• Zone files (data/zones/*.json): Game truth without coordinates

Authors work with SQLite maps. Zone files are exported for game server use.

Component Dependencies

Inputs: - initial-load: Interval trigger for startup - zones-files-store: List of exported zone files - selected-file: Currently selected map ID - workspace-map-row (pattern): Clickable Workspace table rows - new-map-btn: Open new map modal - new-map-cancel-btn: Close modal - new-map-create-btn: Create new zone - save-map-btn: Save current map - export-zone-btn: Export zone JSON

Outputs: - zone-files-list-container: Rendered zone export list - exports-status-indicator: Export status display - selected-file: Selected map ID - current-zone-data: Loaded map data - current-zone: Zone name display - selected-room: Room selection (cleared on map change) - new-map-modal: Modal visibility - has-unsaved-changes: Unsaved flag - save-map-btn: Save button state - status-indicator: Status display

Functions

load_zone_files_list(_, __)	Load list of exported zone files from the zones directory.
render_zone_files_list(files)	Render the exported zone file list.
render_export_status(payload)	Render the latest export status feedback in the exports card.
handle_zone_file_click(zone_clicks, close_clicks)	Open a modal showing the selected zone JSON.
render_file_properties(selected_file, ...)	Render the file properties summary in the right column.
request_file_delete(delete_clicks, cancel_clicks, ...)	Open confirmation modal when a delete button is clicked.
confirm_file_delete(confirm_clicks, pending, selected_file)	Delete a file after confirmation and refresh the relevant list.
handle_file_click(map_clicks, current_file)	Load map data when a Workspace table row is clicked.
handle_new_map_modal(open_clicks, cancel_clicks, ...)	Open, close, and create new maps from a single modal callback.
update_save_status(has_unsaved, selected_file)	Update save/export button state and status indicator.
save_map_to_file(n_clicks, zone_data, selected_file, ...)	Save the current map data to SQLite.
export_zone_to_file(n_clicks, zone_data, ...)	Export the current map as a zone file (strips coordinates).
poll_io_jobs(n_intervals, io_jobs)	Poll background I/O jobs and surface completion feedback.

Module Contents

pipeworks_mud_mapper.callbacks.file_callbacks.load_zone_files_list(_, __)

Load list of exported zone files from the zones directory.

This callback is triggered on initial page load and after export feedback updates so the list reflects newly exported files.

pipeworks_mud_mapper.callbacks.file_callbacks.render_zone_files_list(files)

Render the exported zone file list.

pipeworks_mud_mapper.callbacks.file_callbacks.render_export_status(payload)

Render the latest export status feedback in the exports card.

pipeworks_mud_mapper.callbacks.file_callbacks.handle_zone_file_click(zone_clicks, close_clicks)

Open a modal showing the selected zone JSON.

pipeworks_mud_mapper.callbacks.file_callbacks.render_file_properties(selected_file, selected_zone_file, selected_room, zone_data)

Render the file properties summary in the right column.

pipeworks_mud_mapper.callbacks.file_callbacks.request_file_delete(delete_clicks, cancel_clicks, selected_file, selected_zone_file)

Open confirmation modal when a delete button is clicked.

pipeworks_mud_mapper.callbacks.file_callbacks.confirm_file_delete(confirm_clicks, pending, selected_file)

Delete a file after confirmation and refresh the relevant list.

pipeworks_mud_mapper.callbacks.file_callbacks.handle_file_click(map_clicks, current_file)

Load map data when a Workspace table row is clicked.

Parameters:

• map_clicks (list[int]) – Click counts for workspace map rows.

• current_file (str | None) – Currently selected map ID (used to avoid redundant reloads).

Returns:

(selected_file, zone_data, zone_display, has_unsaved) or no_update tuple.

Return type:

tuple

pipeworks_mud_mapper.callbacks.file_callbacks.handle_new_map_modal(open_clicks, cancel_clicks, create_clicks, zone_id, zone_name, description)

Open, close, and create new maps from a single modal callback.

This consolidates the previous open/close/create callbacks so only one callback owns the modal state. It routes behavior based on the triggering input and only runs creation logic for the Create button.

pipeworks_mud_mapper.callbacks.file_callbacks.update_save_status(has_unsaved, selected_file)

Update save/export button state and status indicator.

Shows appropriate status based on current state:

• No map loaded: disabled buttons

• Unsaved changes: enabled save, disabled export

• All saved: disabled save, enabled export

Parameters:

• has_unsaved (bool) – Whether there are unsaved changes.

• selected_file (str | None) – Currently selected map ID.

Returns:

(save_disabled, export_disabled, status_text).

Return type:

tuple

pipeworks_mud_mapper.callbacks.file_callbacks.save_map_to_file(n_clicks, zone_data, selected_file, io_jobs)

Save the current map data to SQLite.

Parameters:

• n_clicks (int) – Click count for Save button.

• zone_data (dict | None) – Current map data to save.

• selected_file (str | None) – Target map ID.

Returns:

(unsaved_flag, feedback_alert, jobs, updated_zone_data). On success: False and success message. On error: no_update and error message.

Return type:

tuple

pipeworks_mud_mapper.callbacks.file_callbacks.export_zone_to_file(n_clicks, zone_data, selected_file, io_jobs)

Export the current map as a zone file (strips coordinates).

Exports to data/zones/{name}.json, creating the game truth file that the MUD server consumes.

Parameters:

• n_clicks (int) – Click count for Export button.

• zone_data (dict | None) – Current map data to export.

• selected_file (str | None) – Source map ID (used to derive export name).

Returns:

Feedback alert component.

Return type:

str

pipeworks_mud_mapper.callbacks.file_callbacks.poll_io_jobs(n_intervals, io_jobs)

Poll background I/O jobs and surface completion feedback.