feat: use FileSystemFileHandle to modify a file on the local filesystem (#965)

## Launch Checklist  - [x] Briefly describe the changes in this PR. - [x] Link to related issues. - [x] Include before/after visuals or gifs if this PR includes visual changes. - [ ] Write tests for all new functionality. - [x] Add an entry to `CHANGELOG.md` under the `## main` section. ## Changes - This pull request makes use of the FileSystemFileHandle API to modify a local file. No need to download it - just click save. - I don't know how to cover this functionality by tests so I need directions in case test coverage is required. - The pull request adds [@types/wicg-file-system-access](https://www.npmjs.com/package/@types/wicg-file-system-access) as a new dev dependency which I am not really pleased about but can't think of a way around it. ## Known Limitations - The used File API is only available in when accessed from https or on localhost. - There is no visual indicator that the file has been saved. Previously the browser showed it as a new download. ## Issue - https://github.com/maplibre/maputnik/issues/964 ## Screenshots ### Menu <img src="https://github.com/user-attachments/assets/dfcfc5c2-0019-4857-ba26-224b5598fc11" /> ### Open modal <img src="https://github.com/user-attachments/assets/4e1293e8-16b6-4b86-925b-3bebb49d8ca6" height="200px" /> ### Save modal <img src="https://github.com/user-attachments/assets/4f10e2c0-2dd3-4726-a613-30e0406619b0" height="200px" /> --------- Co-authored-by: Harel M <harel.mazor@gmail.com>
2025-12-28 09:00:02 +00:00 · 2025-01-09 17:54:26 +01:00
parent c6174a57d9
commit d50ea76347
14 changed files with 170 additions and 97 deletions
--- a/src/components/App.tsx
+++ b/src/components/App.tsx
@@ -129,6 +129,7 @@ type AppState = {
    export: boolean
    debug: boolean
  }
+  fileHandle: FileSystemFileHandle | null
 }

 export default class App extends React.Component<any, AppState> {
@@ -284,6 +285,7 @@ export default class App extends React.Component<any, AppState> {
      openlayersDebugOptions: {
        debugToolbox: false,
      },
+      fileHandle: null,
    }

    this.layerWatcher = new LayerWatcher({
@@ -611,7 +613,8 @@ export default class App extends React.Component<any, AppState> {
    }
  }

-  openStyle = (styleObj: StyleSpecification & {id: string}) => {
+  openStyle = (styleObj: StyleSpecification & {id: string}, fileHandle: FileSystemFileHandle | null) => {
+    this.setState({fileHandle: fileHandle});
    styleObj = this.setDefaultValues(styleObj)
    this.onStyleChanged(styleObj)
  }
@@ -847,6 +850,10 @@ export default class App extends React.Component<any, AppState> {
    this.setModal(modalName, !this.state.isOpen[modalName]);
  }

+  onSetFileHandle(fileHandle: FileSystemFileHandle | null) {
+    this.setState({fileHandle: fileHandle});
+  }
+
  onChangeOpenlayersDebug = (key: keyof AppState["openlayersDebugOptions"], value: boolean) => {
    this.setState({
      openlayersDebugOptions: {
@@ -949,11 +956,14 @@ export default class App extends React.Component<any, AppState> {
        onStyleChanged={this.onStyleChanged}
        isOpen={this.state.isOpen.export}
        onOpenToggle={this.toggleModal.bind(this, 'export')}
+        fileHandle={this.state.fileHandle}
+        onSetFileHandle={this.onSetFileHandle}
      />
      <ModalOpen
        isOpen={this.state.isOpen.open}
        onStyleOpen={this.openStyle}
        onOpenToggle={this.toggleModal.bind(this, 'open')}
+        fileHandle={this.state.fileHandle}
      />
      <ModalSources
        mapStyle={this.state.mapStyle}
--- a/src/components/AppToolbar.tsx
+++ b/src/components/AppToolbar.tsx
@@ -2,7 +2,15 @@ import React from 'react'
 import classnames from 'classnames'
 import {detect} from 'detect-browser';

-import {MdFileDownload, MdOpenInBrowser, MdSettings, MdLayers, MdHelpOutline, MdFindInPage, MdLanguage} from 'react-icons/md'
+import {
+  MdOpenInBrowser,
+  MdSettings,
+  MdLayers,
+  MdHelpOutline,
+  MdFindInPage,
+  MdLanguage,
+  MdSave
+} from 'react-icons/md'
 import pkgJson from '../../package.json'
 //@ts-ignore
 import maputnikLogo from 'maputnik-design/logos/logo-color.svg?inline'
@@ -216,8 +224,8 @@ class AppToolbarInternal extends React.Component<AppToolbarInternalProps> {
            <IconText>{t("Open")}</IconText>
          </ToolbarAction>
          <ToolbarAction wdKey="nav:export" onClick={this.props.onToggleModal.bind(this, 'export')}>
-            <MdFileDownload />
-            <IconText>{t("Export")}</IconText>
+            <MdSave />
+            <IconText>{t("Save")}</IconText>
          </ToolbarAction>
          <ToolbarAction wdKey="nav:sources" onClick={this.props.onToggleModal.bind(this, 'sources')}>
            <MdLayers />
--- a/src/components/ModalExport.tsx
+++ b/src/components/ModalExport.tsx
@@ -4,7 +4,7 @@ import {saveAs} from 'file-saver'
 import {version} from 'maplibre-gl/package.json'
 import {format} from '@maplibre/maplibre-gl-style-spec'
 import type {StyleSpecification} from 'maplibre-gl'
-import {MdFileDownload} from 'react-icons/md'
+import {MdMap, MdSave} from 'react-icons/md'
 import { WithTranslation, withTranslation } from 'react-i18next';

 import FieldString from './FieldString'
@@ -22,6 +22,8 @@ type ModalExportInternalProps = {
  onStyleChanged(...args: unknown[]): unknown
  isOpen: boolean
  onOpenToggle(...args: unknown[]): unknown
+  onSetFileHandle(fileHandle: FileSystemFileHandle | null): unknown
+  fileHandle: FileSystemFileHandle | null
 } & WithTranslation;


@@ -47,7 +49,7 @@ class ModalExportInternal extends React.Component<ModalExportInternalProps> {
    }
  }

-  downloadHtml() {
+  createHtml() {
    const tokenStyle = this.tokenizedStyle();
    const htmlTitle = this.props.mapStyle.name || this.props.t("Map");
    const html = `<!DOCTYPE html>
@@ -81,11 +83,49 @@ class ModalExportInternal extends React.Component<ModalExportInternalProps> {
    saveAs(blob, exportName + ".html");
  }

-  downloadStyle() {
+  async saveStyle() {
    const tokenStyle = this.tokenizedStyle();
-    const blob = new Blob([tokenStyle], {type: "application/json;charset=utf-8"});
-    const exportName = this.exportName();
-    saveAs(blob, exportName + ".json");
+
+    let fileHandle = this.props.fileHandle;
+    if (fileHandle == null) {
+      fileHandle = await this.createFileHandle();
+      this.props.onSetFileHandle(fileHandle)
+      if (fileHandle == null) return;
+    }
+
+    const writable = await fileHandle.createWritable();
+    await writable.write(tokenStyle);
+    await writable.close();
+    this.props.onOpenToggle();
+  }
+
+  async saveStyleAs() {
+    const tokenStyle = this.tokenizedStyle();
+
+    const fileHandle = await this.createFileHandle();
+    this.props.onSetFileHandle(fileHandle)
+    if (fileHandle == null) return;
+
+    const writable = await fileHandle.createWritable();
+    await writable.write(tokenStyle);
+    await writable.close();
+    this.props.onOpenToggle();
+  }
+
+  async createFileHandle() : Promise<FileSystemFileHandle | null> {
+    const pickerOpts: SaveFilePickerOptions = {
+      types: [
+        {
+          description: "json",
+          accept: { "application/json": [".json"] },
+        },
+      ],
+      suggestedName: this.exportName(),
+    };
+
+    const fileHandle = await window.showSaveFilePicker(pickerOpts) as FileSystemFileHandle;
+    this.props.onSetFileHandle(fileHandle)
+    return fileHandle;
  }

  changeMetadataProperty(property: string, value: any) {
@@ -107,14 +147,14 @@ class ModalExportInternal extends React.Component<ModalExportInternalProps> {
      data-wd-key="modal:export"
      isOpen={this.props.isOpen}
      onOpenToggle={this.props.onOpenToggle}
-      title={t('Export Style')}
+      title={t('Save Style')}
      className="maputnik-export-modal"
    >

      <section className="maputnik-modal-section">
-        <h1>{t("Download Style")}</h1>
+        <h1>{t("Save Style")}</h1>
        <p>
-          {t("Download a JSON style to your computer.")}
+          {t("Save the JSON style to your computer.")}
        </p>

        <div>
@@ -140,17 +180,23 @@ class ModalExportInternal extends React.Component<ModalExportInternalProps> {

        <div className="maputnik-modal-export-buttons">
          <InputButton
-            onClick={this.downloadStyle.bind(this)}
+            onClick={this.saveStyle.bind(this)}
          >
-            <MdFileDownload />
-            {t("Download Style")}
+            <MdSave />
+            {t("Save")}
+          </InputButton>
+          <InputButton
+            onClick={this.saveStyleAs.bind(this)}
+          >
+            <MdSave />
+            {t("Save as")}
          </InputButton>

          <InputButton
-            onClick={this.downloadHtml.bind(this)}
+            onClick={this.createHtml.bind(this)}
          >
-            <MdFileDownload />
-            {t("Download HTML")}
+            <MdMap />
+            {t("Create HTML")}
          </InputButton>
        </div>
      </section>
--- a/src/components/ModalOpen.tsx
+++ b/src/components/ModalOpen.tsx
@@ -1,7 +1,6 @@
 import React, { FormEvent } from 'react'
 import {MdFileUpload} from 'react-icons/md'
 import {MdAddCircleOutline} from 'react-icons/md'
-import FileReaderInput, { Result } from 'react-file-reader-input'
 import { Trans, WithTranslation, withTranslation } from 'react-i18next';

 import ModalLoading from './ModalLoading'
@@ -47,6 +46,7 @@ type ModalOpenInternalProps = {
  isOpen: boolean
  onOpenToggle(...args: unknown[]): unknown
  onStyleOpen(...args: unknown[]): unknown
+  fileHandle: FileSystemFileHandle | null
 } & WithTranslation;

 type ModalOpenState = {
@@ -135,29 +135,37 @@ class ModalOpenInternal extends React.Component<ModalOpenInternalProps, ModalOpe
    this.onStyleSelect(this.state.styleUrl);
  }

-  onUpload = (_: any, files: Result[]) => {
-    const [, file] = files[0];
-    const reader = new FileReader();
-
+  onOpenFile = async () => {
    this.clearError();

-    reader.readAsText(file, "UTF-8");
-    reader.onload = e => {
-      let mapStyle;
-      try {
-        mapStyle = JSON.parse(e.target?.result as string)
-      }
-      catch(err) {
-        this.setState({
-          error: (err as Error).toString()
-        });
-        return;
-      }
-      mapStyle = style.ensureStyleValidity(mapStyle)
-      this.props.onStyleOpen(mapStyle);
-      this.onOpenToggle();
+    const pickerOpts: OpenFilePickerOptions = {
+      types: [
+        {
+          description: "json",
+          accept: { "application/json": [".json"] },
+        },
+      ],
+      multiple: false,
+    };
+
+    const [fileHandle] = await window.showOpenFilePicker(pickerOpts) as Array<FileSystemFileHandle>;
+    const file = await fileHandle.getFile();
+    const content = await file.text();
+
+    let mapStyle;
+    try {
+      mapStyle = JSON.parse(content)
+    } catch (err) {
+      this.setState({
+        error: (err as Error).toString()
+      });
+      return;
    }
-    reader.onerror = e => console.log(e.target);
+    mapStyle = style.ensureStyleValidity(mapStyle)
+
+    this.props.onStyleOpen(mapStyle, fileHandle);
+    this.onOpenToggle();
+    return file;
  }

  onOpenToggle() {
@@ -196,7 +204,7 @@ class ModalOpenInternal extends React.Component<ModalOpenInternalProps, ModalOpe
      );
    }

-    return  (
+    return (
      <div>
        <Modal
          data-wd-key="modal:open"
@@ -206,11 +214,14 @@ class ModalOpenInternal extends React.Component<ModalOpenInternalProps, ModalOpe
        >
          {errorElement}
          <section className="maputnik-modal-section">
-            <h1>{t("Upload Style")}</h1>
-            <p>{t("Upload a JSON style from your computer.")}</p>
-            <FileReaderInput onChange={this.onUpload} tabIndex={-1} aria-label={t("Style file")}>
-              <InputButton className="maputnik-upload-button"><MdFileUpload /> {t("Upload")}</InputButton>
-            </FileReaderInput>
+            <h1>{t("Open local Style")}</h1>
+            <p>{t("Open a local JSON style from your computer.")}</p>
+            <div>
+              <InputButton
+                className="maputnik-big-button"
+                onClick={this.onOpenFile}><MdFileUpload/> {t("Open Style")}
+              </InputButton>
+            </div>
          </section>

          <section className="maputnik-modal-section">
--- a/src/locales/README.md
+++ b/src/locales/README.md
@@ -1,6 +1,6 @@
 ## Internationalization

-The process of internationlization is pretty straight forward for Maputnik.
+The process of internationalization is pretty straight forward for Maputnik.

 ## Add a new language

--- a/src/locales/de/translation.json
+++ b/src/locales/de/translation.json
@@ -29,7 +29,7 @@
  "Map view": "Kartenansicht",
  "Maputnik on GitHub": "Maputnik auf GitHub",
  "Open": "Öffnen",
-  "Export": "Exportieren",
+  "Save": "Speichern",
  "Data Sources": "Datenquellen",
  "Style Settings": "Stileinstellungen",
  "View": "Ansicht",
@@ -81,17 +81,14 @@
  "Close modal": "Modale Fenster schließen",
  "Debug": "Debug",
  "Options": "Optionen",
-  "<0>Open in OSM</0> &mdash; Opens the current view on openstreetmap.org": "<0>In OSM öffnen</0> &mdash; Öffnet die aktuelle Ansicht auf openstreetmap.org",
-  "Export Style": "Stil exportieren",
-  "Download Style": "Stil herunterladen",
-  "Download a JSON style to your computer.": "Lade einen JSON-Stil auf deinen Computer herunter.",
-  "Download HTML": "HTML herunterladen",
+  "Save Style": "Stil Speichern",
+  "Save the JSON style to your computer.": "Speichere den JSON Stil auf deinem Computer.",
+  "Save as": "Speichern unter",
+  "Create HTML": "HTML erstellen",
  "Cancel": "Abbrechen",
  "Open Style": "Stil öffnen",
-  "Upload Style": "Stil hochladen",
-  "Upload a JSON style from your computer.": "Lade einen JSON-Stil von deinem Computer hoch.",
-  "Style file": "Stildatei",
-  "Upload": "Hochladen",
+  "Open local Style": "Lokalen Stil öffnen",
+  "Open a local JSON style from your computer.": "Öffne einen lokalen JSON Stil von deinem Computer.",
  "Load from URL": "Von URL laden",
  "Load from a URL. Note that the URL must have <1>CORS enabled</1>.": "Von einer URL laden. Beachte, dass die URL <1>CORS aktiviert</1> haben muss.",
  "Style URL": "Stil-URL",
--- a/src/locales/fr/translation.json
+++ b/src/locales/fr/translation.json
@@ -29,7 +29,7 @@
  "Map view": "Vue de la carte",
  "Maputnik on GitHub": "Maputnik sur GitHub",
  "Open": "Ouvrir",
-  "Export": "Exporter",
+  "Save": "Enregistrer",
  "Data Sources": "Sources de données",
  "Style Settings": "Paramètres du style",
  "View": "Vue",
@@ -81,17 +81,14 @@
  "Close modal": "Fermer la fenêtre modale",
  "Debug": "Déboguer",
  "Options": "Options",
-  "<0>Open in OSM</0> &mdash; Opens the current view on openstreetmap.org": "<0>Ouvrir dans OSM</0> &mdash; Ouvre la vue actuelle sur openstreetmap.org",
-  "Export Style": "Exporter le style",
-  "Download Style": "Télécharger le style",
-  "Download a JSON style to your computer.": "Téléchargez un style JSON sur votre ordinateur.",
-  "Download HTML": "Télécharger HTML",
+  "Save Style": "Enregistrer le style",
+  "Save the JSON style to your computer.": "Enregistrer le style JSON sur votre ordinateur.",
+  "Save as": "Enregistrer sous",
+  "Create HTML": "Créer le HTML",
  "Cancel": "Annuler",
  "Open Style": "Ouvrir le style",
-  "Upload Style": "Transférer un style",
-  "Upload a JSON style from your computer.": "Transférer un style JSON depuis votre ordinateur.",
-  "Style file": "Fichier de style",
-  "Upload": "Transférer",
+  "Open local Style": "Ouvrir un style local",
+  "Open a local JSON style from your computer.": "Ouvrir un style JSON local depuis votre ordinateur.",
  "Load from URL": "Charger depuis une URL",
  "Load from a URL. Note that the URL must have <1>CORS enabled</1>.": "Charger depuis une URL. Notez que l'URL doit avoir les <1>CORS activés</1>.",
  "Style URL": "URL du style",
--- a/src/locales/he/translation.json
+++ b/src/locales/he/translation.json
@@ -29,7 +29,7 @@
  "Map view": "תצוגת מפה",
  "Maputnik on GitHub": "מפוטניק בגיטהב",
  "Open": "פתיחה",
-  "Export": "ייצוא",
+  "Save": "שמור",
  "Data Sources": "מקורות מידע",
  "Style Settings": "הגדרות הסטייל",
  "View": "תצוגה",
@@ -81,16 +81,14 @@
  "Close modal": "סגירת חלונית",
  "Debug": "דיבאג",
  "Options": "אפשרויות",
-  "Export Style": "ייצוא של הסטייל",
-  "Download Style": "הורדה של הסטייל",
-  "Download a JSON style to your computer.": "הורדה של הסטייל למחשב",
-  "Download HTML": "הורדה כ-HTML",
+  "Save Style": "שמירת הסטייל",
+  "Save the JSON style to your computer.": "שמירת הסטייל JSON במחשב שלך.",
+  "Save as": "שמירה בשם",
+  "Create HTML": "צור HTML",
  "Cancel": "ביטול",
  "Open Style": "פתיחת סטייל",
-  "Upload Style": "העלאה של סטייל",
-  "Upload a JSON style from your computer.": "העלאה של סטייל מהמחשב",
-  "Style file": "קובץ סטייל",
-  "Upload": "העלאה",
+  "Open local Style": "פתיחת סטייל מקומי",
+  "Open a local JSON style from your computer.": "פתיחת סטייל JSON מקומי מהמחשב שלך.",
  "Load from URL": "פתיחה מתוך כתובת",
  "Load from a URL. Note that the URL must have <1>CORS enabled</1>.": "פתיחה מכתובת, שימו לב: הכתובת צריכה לתמוך ב- CORS",
  "Style URL": "כתוסת סטייל",
--- a/src/locales/ja/translation.json
+++ b/src/locales/ja/translation.json
@@ -29,7 +29,7 @@
  "Map view": "地図画面",
  "Maputnik on GitHub": "GitHubのMaputnik",
  "Open": "開く",
-  "Export": "エクスポート",
+  "Save": "保存",
  "Data Sources": "データソース",
  "Style Settings": "スタイル設定",
  "View": "表示",
@@ -81,16 +81,14 @@
  "Close modal": "モーダルを閉じる",
  "Debug": "デバッグ",
  "Options": "設定",
-  "Export Style": "スタイルをエクスポート",
-  "Download Style": "スタイルをダウンロード",
-  "Download a JSON style to your computer.": "パソコンにJSONスタイルをダウンロードします。",
-  "Download HTML": "HTMLをダウンロード",
+  "Save Style": "スタイルを保存",
+  "Save the JSON style to your computer.": "JSONスタイルをコンピュータに保存します。",
+  "Save as": "名前を付けて保存",
+  "Create HTML": "HTMLを作成",
  "Cancel": "キャンセル",
  "Open Style": "スタイルを開く",
-  "Upload Style": "スタイルをアップロードする",
-  "Upload a JSON style from your computer.": "JSONスタイルをパソコンからアップロードする",
-  "Style file": "スタイルファイル",
-  "Upload": "アップロード",
+  "Open local Style": "ローカルスタイルを開く",
+  "Open a local JSON style from your computer.": "コンピュータからローカルJSONスタイルを開きます。",
  "Load from URL": "URLから読み込む",
  "Load from a URL. Note that the URL must have <1>CORS enabled</1>.": "URLから読み込む。注意: URLは <1>CORSを有効にする</1> 必要があります。",
  "Style URL": "スタイルURL",
--- a/src/locales/zh/translation.json
+++ b/src/locales/zh/translation.json
@@ -29,7 +29,7 @@
  "Map view": "地图视图",
  "Maputnik on GitHub": "GitHub上的Maputnik",
  "Open": "打开",
-  "Export": "导出",
+  "Save": "保存",
  "Data Sources": "数据源",
  "Style Settings": "样式设置",
  "View": "视图",
@@ -81,16 +81,14 @@
  "Close modal": "关闭模态框",
  "Debug": "调试",
  "Options": "选项",
-  "Export Style": "导出样式",
-  "Download Style": "下载样式",
-  "Download a JSON style to your computer.": "将JSON样式下载到您的电脑。",
-  "Download HTML": "下载HTML",
+  "Save Style": "保存样式",
+  "Save the JSON style to your computer.": "将JSON样式保存到您的计算机。",
+  "Save as": "另存为",
+  "Create HTML": "创建HTML",
  "Cancel": "取消",
  "Open Style": "打开样式",
-  "Upload Style": "上传样式",
-  "Upload a JSON style from your computer.": "从您的电脑上传JSON样式。",
-  "Style file": "样式文件",
-  "Upload": "上传",
+  "Open local Style": "打开本地样式",
+  "Open a local JSON style from your computer.": "从您的计算机打开本地JSON样式。",
  "Load from URL": "从URL加载",
  "Load from a URL. Note that the URL must have <1>CORS enabled</1>.": "从URL加载。注意：URL必须启用 <1>CORS</1>。",
  "Style URL": "样式URL",