browse.js 0.0.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,8 @@
+# Browse.js
+## A lightweight yet versatile file browser written in vanilla JavaScript.
+
+Open `demo/index.html` in a browser (for example, using `python -m http.server 8000`) to run a demo.
+
+![Browse.js Screenshot](./demo/screenshot-simple.png)
+
+© 2026 Daniel Foerster. All rights reserved. Made available under the Apache 2.0 license; see [LICENSE](./LICENSE) for details.

package/dist/browse.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @typedef {Object} IconRule
+ * @property {string} icon - The icon URL
+ * @property {function(string):boolean} [typeMatch] - Optional function to match against the MIME type of a file
+ * @property {string[]} [exts] - Optional array of file extensions (with dot) to match against the file name
+ */
+/**
+ * @typedef {Object} FileItem
+ * @property {string} name - The display name of the file or folder
+ * @property {string} [thumbnail] - Optional data URL for the thumbnail image
+ * @property {Object} [meta] - Optional metadata object with additional info (e.g. size, type)
+ * @property {FileItem[]} [children] - If present, indicates this item is a folder containing these child items
+ */
+/**
+ * @typedef {Object} BrowseJSOptions
+ * @property {string} [rootName] - The display name for the root folder (default: "Root")
+ * @property {function(FileItem, number):void} [onSelect] - Callback when a file is selected, receives the file item and its index
+ * @property {string} [detailsText] - Default text to show in the details pane when no selection is made (default: "Select a file")
+ * @property {Object} [icons] - Custom icons configuration
+ * @property {IconRule[]} [icons.rules] - Custom rules for determining icons based on MIME type or file extension
+ * @property {string} [icons.folder] - Custom icon URL for folders
+ * @property {string} [icons.default] - Custom icon URL for files that don't match any rule
+ * @property {boolean} [multiSelect] - If true, allows selecting multiple files (default: false)
+ * @property {function(string):?(FileItem)} [onCreateFolder] - Optional callback invoked when creating a new folder. If it returns a FileItem, it will be added to the current folder.
+ * @property {function(File[]):?(FileItem|FileItem[])} [onUpload] - Optional callback invoked when files are uploaded. If it returns FileItem(s), they'll be added to the current folder.
+ */
+export class BrowseJS {
+    /**
+     * @param {string|Element} container - The the container element to render the gallery into. Can be a DOM element, ID, or selector string.
+     * @param {FileItem[]} files - An array of file items to display in the root folder
+     * @param {BrowseJSOptions} opts - Configuration options (see BrowseJSOptions typedef for details)
+     */
+    constructor(container: string | Element, files?: FileItem[], opts?: BrowseJSOptions);
+    container: Element;
+    opts: BrowseJSOptions;
+    iconRules: {
+        icon: string;
+        typeMatch: (t: any) => any;
+        exts: string[];
+    }[] | IconRule[];
+    folderIcon: string;
+    defaultIcon: string;
+    multi: boolean;
+    selectedIndices: any;
+    stack: {
+        name: string;
+        files: FileItem[];
+    }[];
+    breadcrumbEl: HTMLElement;
+    crumbsWrap: HTMLDivElement;
+    controlsEl: HTMLDivElement;
+    detailsEl: HTMLElement;
+    galleryEl: HTMLDivElement;
+    _fileInput: HTMLInputElement;
+    getIconForItem(item: any): string;
+    render(): void;
+    updateSelectionUI(): void;
+    renderDetails(): void;
+    renderBreadcrumb(): void;
+    currentFolder(): string;
+    currentFiles(): FileItem[];
+    addFiles(files: any): void;
+    getSelectedPaths(): any[];
+    handleCreateFolder(): Promise<void>;
+    _creatingFolder: boolean;
+    handleUpload(): Promise<void>;
+    handleDropFiles(files: any): Promise<void>;
+    select(i: any): void;
+    enterFolder(i: any): void;
+    goToCrumb(idx: any): void;
+}
+export type IconRule = {
+    /**
+     * - The icon URL
+     */
+    icon: string;
+    /**
+     * - Optional function to match against the MIME type of a file
+     */
+    typeMatch?: (arg0: string) => boolean;
+    /**
+     * - Optional array of file extensions (with dot) to match against the file name
+     */
+    exts?: string[];
+};
+export type FileItem = {
+    /**
+     * - The display name of the file or folder
+     */
+    name: string;
+    /**
+     * - Optional data URL for the thumbnail image
+     */
+    thumbnail?: string;
+    /**
+     * - Optional metadata object with additional info (e.g. size, type)
+     */
+    meta?: any;
+    /**
+     * - If present, indicates this item is a folder containing these child items
+     */
+    children?: FileItem[];
+};
+export type BrowseJSOptions = {
+    /**
+     * - The display name for the root folder (default: "Root")
+     */
+    rootName?: string;
+    /**
+     * - Callback when a file is selected, receives the file item and its index
+     */
+    onSelect?: (arg0: FileItem, arg1: number) => void;
+    /**
+     * - Default text to show in the details pane when no selection is made (default: "Select a file")
+     */
+    detailsText?: string;
+    /**
+     * - Custom icons configuration
+     */
+    icons?: {
+        rules?: IconRule[];
+        folder?: string;
+        default?: string;
+    };
+    /**
+     * - If true, allows selecting multiple files (default: false)
+     */
+    multiSelect?: boolean;
+    /**
+     * - Optional callback invoked when creating a new folder. If it returns a FileItem, it will be added to the current folder.
+     */
+    onCreateFolder?: (arg0: string) => (FileItem) | null;
+    /**
+     * - Optional callback invoked when files are uploaded. If it returns FileItem(s), they'll be added to the current folder.
+     */
+    onUpload?: (arg0: File[]) => (FileItem | FileItem[]) | null;
+};

package/dist/browse.js

@@ -0,0 +1 @@
+function svgDataUrlFromSvg(svg){return"data:image/svg+xml;utf8,"+encodeURIComponent(svg)}function escapeText(t){return String(t).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;")}function svgDocumentIcon(label,bg="#e9eefc",w=240,h=310){const safe=escapeText(label||"");const fold=84;const bodyPath=`M0 0 H${w-fold} L${w} ${fold} V${h} H0 Z`;const foldPath=`M${w-fold} 0 v${fold} h${fold} Z`;const svg=`<?xml version='1.0' encoding='utf-8'?><svg xmlns='http://www.w3.org/2000/svg' width='${w}' height='${h}' viewBox='0 0 ${w} ${h}'>`+`<path d='${bodyPath}' fill='${bg}' stroke='#0b12200a' stroke-linejoin='round'/>`+`<path d='${foldPath}' fill='#0000001a' stroke='#0b122005'/>`+`<text x='50%' y='58%' dominant-baseline='middle' text-anchor='middle' font-family='Inter,Arial,Helvetica,sans-serif' font-size='36' fill='#0b1220'>${safe}</text>`+`</svg>`;return svgDataUrlFromSvg(svg)}function svgFolderIcon(label,bg="#ffd7a8",w=420,h=320){const safe=escapeText(label||"");const tabH=44;const tabW=120;const svg=`<?xml version='1.0' encoding='utf-8'?><svg xmlns='http://www.w3.org/2000/svg' width='${w}' height='${h}' viewBox='0 0 ${w} ${h}'>`+`<rect x='6' y='34' rx='12' ry='12' width='${w-12}' height='${h-40}' fill='${bg}' stroke='#0b12200a'/>`+`<rect x='18' y='12' rx='8' ry='8' width='${tabW}' height='${tabH}' fill='${bg}'/>`+`<text x='50%' y='62%' dominant-baseline='middle' text-anchor='middle' font-family='Inter,Arial,Helvetica,sans-serif' font-size='36' fill='#0b1220'>${safe}</text>`+`</svg>`;return svgDataUrlFromSvg(svg)}const DEFAULT_ICON_RULES=[{icon:svgDocumentIcon("IMG","#c7ddff"),typeMatch:t=>t.startsWith("image/"),exts:[".png",".jpg",".jpeg",".gif",".webp",".bmp",".svg",".avif"]},{icon:svgDocumentIcon("PDF","#ffd7d7"),typeMatch:t=>t==="application/pdf",exts:[".pdf"]},{icon:svgDocumentIcon("AUD","#e6dcff"),typeMatch:t=>t.startsWith("audio/"),exts:[".mp3",".wav",".m4a",".flac"]},{icon:svgDocumentIcon("VID","#dff7ff"),typeMatch:t=>t.startsWith("video/"),exts:[".mp4",".mov",".webm",".mkv"]},{icon:svgDocumentIcon("DOC","#dfe6ff"),typeMatch:t=>["application/msword","application/vnd.openxmlformats-officedocument.wordprocessingml.document"].includes(t),exts:[".doc",".docx",".odt"]},{icon:svgDocumentIcon("XLS","#e4ffd7"),typeMatch:t=>["text/csv","application/vnd.ms-excel","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"].includes(t),exts:[".xls",".xlsx",".ods",".csv"]},{icon:svgDocumentIcon("ZIP","#fffed7"),typeMatch:t=>t.includes("zip")||t==="application/x-zip-compressed",exts:[".zip",".tar",".gz"]},{icon:svgDocumentIcon("TXT","#eaeaea"),typeMatch:t=>t.startsWith("text/"),exts:[".txt",".md",".log"]}];export class BrowseJS{constructor(container,files=[],opts={}){if(container instanceof Element){this.container=container}else{const containerElement=document.getElementById(container)||document.querySelector(container);if(!containerElement)throw new Error("Container not found: "+container);this.container=containerElement}this.opts=opts;this.iconRules=opts.icons&&opts.icons.rules?opts.icons.rules:DEFAULT_ICON_RULES;this.folderIcon=opts.icons&&opts.icons.folder?opts.icons.folder:svgFolderIcon("");this.defaultIcon=opts.icons&&opts.icons.default?opts.icons.default:svgDocumentIcon("?","#e9eefc");this.multi=Boolean(opts.multiSelect);this.selectedIndices=new Set;this.stack=[{name:opts.rootName||"Root",files:files}];this.breadcrumbEl=document.createElement("nav");this.breadcrumbEl.className="breadcrumb";this.breadcrumbEl.setAttribute("aria-label","Breadcrumb");this.crumbsWrap=document.createElement("div");this.crumbsWrap.className="crumbs-wrap";this.controlsEl=document.createElement("div");this.controlsEl.className="crumb-controls";this.breadcrumbEl.appendChild(this.crumbsWrap);this.breadcrumbEl.appendChild(this.controlsEl);this.detailsEl=document.createElement("aside");this.detailsEl.className="details";this.detailsEl.setAttribute("aria-live","polite");this.detailsEl.textContent=opts.detailsText||"Select a file";this.container.innerHTML="";this.galleryEl=document.createElement("div");this.galleryEl.className="gallery-grid";this.container.appendChild(this.breadcrumbEl);this.container.appendChild(this.galleryEl);this.container.appendChild(this.detailsEl);this._fileInput=document.createElement("input");this._fileInput.type="file";this._fileInput.style.display="none";this.container.appendChild(this._fileInput);this.container.classList.add("browsejs");this.galleryEl.tabIndex=0;document.addEventListener("dragover",e=>{e.preventDefault();this.container.classList.add("dragover")});document.addEventListener("dragleave",e=>{this.container.classList.remove("dragover")});this.container.addEventListener("drop",e=>{e.preventDefault();this.container.classList.remove("dragover");const files=Array.from(e.dataTransfer&&e.dataTransfer.files||[]);if(files.length===0)return;this.handleDropFiles(files)});this.render()}getIconForItem(item){if(item.children)return this.folderIcon;const type=item.meta&&item.meta.type?String(item.meta.type).toLowerCase():"";const name=item.name?String(item.name).toLowerCase():"";if(type){for(const r of this.iconRules){if(r.typeMatch&&r.typeMatch(type))return r.icon}}for(const r of this.iconRules){if(r.exts){for(const e of r.exts){if(name.endsWith(e))return r.icon}}}return this.defaultIcon}render(){this.galleryEl.innerHTML="";const list=this.currentFiles();list.forEach((f,i)=>{const card=document.createElement("button");card.className="card";card.type="button";card.dataset.index=i;card.title=f.name;const img=document.createElement("img");img.alt=f.name||"";img.src=f.thumbnail||this.getIconForItem(f);const meta=document.createElement("div");meta.className="meta";meta.textContent=f.name;card.appendChild(img);card.appendChild(meta);if(f.children&&Array.isArray(f.children)){card.addEventListener("click",()=>this.enterFolder(i));card.addEventListener("keyup",e=>{if(e.key==="Enter")this.enterFolder(i)})}else{card.addEventListener("click",()=>this.select(i));card.addEventListener("keyup",e=>{if(e.key==="Enter")this.select(i)})}this.galleryEl.appendChild(card)});this.updateSelectionUI();this.renderBreadcrumb()}updateSelectionUI(){const cards=this.galleryEl.querySelectorAll(".card");cards.forEach(c=>{const idx=Number(c.dataset.index);if(this.selectedIndices.has(idx))c.classList.add("selected");else c.classList.remove("selected")});this.renderDetails()}renderDetails(){if(!this.detailsEl)return;const activeList=this.currentFiles();if(this.selectedIndices.size===0){this.detailsEl.innerHTML='<p class="small">No selection</p>'}else if(this.selectedIndices.size>1){const indices=Array.from(this.selectedIndices).sort();this.detailsEl.innerHTML="";const header=document.createElement("div");header.innerHTML=`<strong>${indices.length} item${indices.length>1?"s":""} selected</strong>`;this.detailsEl.appendChild(header);const list=document.createElement("div");list.className="small";list.innerHTML=indices.map(i=>`<div>${escapeText(activeList[i]&&activeList[i].name||"Untitled")}</div>`).join("");this.detailsEl.appendChild(list)}else{const index=Array.from(this.selectedIndices)[0];const item=activeList[index];if(!item){this.detailsEl.innerHTML='<p class="small">No selection</p>';return}this.detailsEl.innerHTML="";const img=document.createElement("img");img.className="preview";img.src=item.thumbnail||this.galleryEl.querySelector(`.card[data-index="${index}"] img`)?.src||this.getIconForItem(item);img.alt=item.name||"preview";const name=document.createElement("div");name.innerHTML=`<strong>${item.name||"Untitled"}</strong>`;const meta=document.createElement("div");meta.className="small";if(item.meta&&typeof item.meta==="object"){meta.innerHTML=Object.entries(item.meta).map(([k,v])=>`<div><strong>${k}:</strong> ${v}</div>`).join("")}else if(item.meta){meta.textContent=String(item.meta)}else{meta.textContent=""}this.detailsEl.appendChild(img);this.detailsEl.appendChild(name);this.detailsEl.appendChild(meta)}}renderBreadcrumb(){if(!this.breadcrumbEl)return;this.crumbsWrap.innerHTML="";this.stack.forEach((s,idx)=>{const btn=document.createElement("button");btn.type="button";btn.className="crumb";btn.textContent=s.name;btn.addEventListener("click",()=>this.goToCrumb(idx));this.crumbsWrap.appendChild(btn);if(idx<this.stack.length-1){const sep=document.createElement("span");sep.className="sep";sep.textContent="»";this.crumbsWrap.appendChild(sep)}});this.controlsEl.innerHTML="";const hasCreate=typeof this.opts.onCreateFolder==="function";const hasUpload=typeof this.opts.onUpload==="function";if(hasCreate){const createBtn=document.createElement("button");createBtn.type="button";createBtn.className="crumb-action";createBtn.textContent="New Folder";createBtn.addEventListener("click",()=>this.handleCreateFolder());this.controlsEl.appendChild(createBtn)}if(hasUpload){const uploadBtn=document.createElement("button");uploadBtn.type="button";uploadBtn.className="crumb-action";uploadBtn.textContent="Upload";uploadBtn.addEventListener("click",()=>this.handleUpload());this.controlsEl.appendChild(uploadBtn)}}currentFolder(){return this.stack.map(s=>s.name+"/").slice(1).join()}currentFiles(){return this.stack[this.stack.length-1].files}addFiles(files){if(!Array.isArray(files))files=[files];const current=this.currentFiles();current.push(...files);this.render()}getSelectedPaths(){const activeList=this.currentFiles();const basePath=this.currentFolder();const paths=[];Array.from(this.selectedIndices).forEach(i=>{const item=activeList[i];if(item){paths.push(basePath+item.name)}});return paths}async handleCreateFolder(){if(this._creatingFolder)return;this._creatingFolder=true;const current=this.currentFiles();const card=document.createElement("div");card.className="card creating";card.tabIndex=0;const img=document.createElement("img");img.alt="Folder";img.src=this.folderIcon;const meta=document.createElement("div");meta.className="meta";const nameEl=document.createElement("div");nameEl.className="editable-name";nameEl.contentEditable="true";nameEl.spellcheck=false;nameEl.textContent="";meta.appendChild(nameEl);card.appendChild(img);card.appendChild(meta);this.galleryEl.insertBefore(card,this.galleryEl.firstChild);nameEl.focus();try{const sel=window.getSelection();const range=document.createRange();range.selectNodeContents(nameEl);sel.removeAllRanges();sel.addRange(range)}catch(e){}const cleanup=()=>{this._creatingFolder=false;if(card.parentNode)card.parentNode.removeChild(card)};const commit=async()=>{const name=nameEl.textContent.trim();if(!name){cleanup();return}if(typeof this.opts.onCreateFolder==="function"){const res=await this.opts.onCreateFolder(name);if(res){current.splice(0,0,res)}else{cleanup();return}}else{current.splice(0,0,{name:name,children:[]})}this._creatingFolder=false;this.render()};const onKey=e=>{if(e.key==="Enter"){e.preventDefault();nameEl.blur()}else if(e.key==="Escape"){e.preventDefault();cleanup()}};nameEl.addEventListener("keydown",onKey);nameEl.addEventListener("blur",()=>{setTimeout(()=>{if(!this._creatingFolder)return;commit()},0)},{once:true})}async handleUpload(){if(typeof this.opts.onUpload!=="function")return;this._fileInput.value="";this._fileInput.multiple=true;this._fileInput.onchange=async()=>{const files=Array.from(this._fileInput.files||[]);if(files.length===0)return;try{const res=await this.opts.onUpload(files);if(res){const current=this.currentFiles();if(Array.isArray(res))current.push(...res);else current.push(res);this.render()}}catch(err){console.error("onUpload error",err)}};this._fileInput.click()}async handleDropFiles(files){if(!files||files.length===0)return;if(typeof this.opts.onUpload!=="function")return;try{const res=await this.opts.onUpload(files);if(res){const current=this.currentFiles();if(Array.isArray(res))current.push(...res);else current.push(res);this.render()}}catch(err){console.error("onUpload error",err)}}select(i){const activeList=this.currentFiles();if(this.multi){if(this.selectedIndices.has(i)){this.selectedIndices.delete(i)}else{this.selectedIndices.add(i)}}else{if(this.selectedIndices.has(i)){this.selectedIndices.clear()}else{this.selectedIndices.clear();this.selectedIndices.add(i)}}this.updateSelectionUI();if(typeof this.opts.onSelect==="function"){const indices=Array.from(this.selectedIndices).sort((a,b)=>a-b);const items=indices.map(idx=>activeList[idx]);this.opts.onSelect(items,indices)}}enterFolder(i){const f=this.currentFiles()[i];if(!f||!Array.isArray(f.children))return;this.stack.push({name:f.name||"Folder",files:f.children});this.selectedIndices.clear();this.render()}goToCrumb(idx){this.stack=this.stack.slice(0,idx+1);this.selectedIndices.clear();this.render()}}

package/dist/browse.min.js

@@ -0,0 +1 @@
+function svgDataUrlFromSvg(svg){return"data:image/svg+xml;utf8,"+encodeURIComponent(svg)}function escapeText(t){return String(t).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;")}function svgDocumentIcon(label,bg="#e9eefc",w=240,h=310){return svgDataUrlFromSvg(`<?xml version='1.0' encoding='utf-8'?><svg xmlns='http://www.w3.org/2000/svg' width='${w}' height='${h}' viewBox='0 0 ${w} ${h}'><path d='${`M0 0 H${w-84} L${w} 84 V${h} H0 Z`}' fill='${bg}' stroke='#0b12200a' stroke-linejoin='round'/><path d='${`M${w-84} 0 v84 h84 Z`}' fill='#0000001a' stroke='#0b122005'/><text x='50%' y='58%' dominant-baseline='middle' text-anchor='middle' font-family='Inter,Arial,Helvetica,sans-serif' font-size='36' fill='#0b1220'>${escapeText(label||"")}</text></svg>`)}function svgFolderIcon(label,bg="#ffd7a8",w=420,h=320){return svgDataUrlFromSvg(`<?xml version='1.0' encoding='utf-8'?><svg xmlns='http://www.w3.org/2000/svg' width='${w}' height='${h}' viewBox='0 0 ${w} ${h}'><rect x='6' y='34' rx='12' ry='12' width='${w-12}' height='${h-40}' fill='${bg}' stroke='#0b12200a'/><rect x='18' y='12' rx='8' ry='8' width='120' height='44' fill='${bg}'/><text x='50%' y='62%' dominant-baseline='middle' text-anchor='middle' font-family='Inter,Arial,Helvetica,sans-serif' font-size='36' fill='#0b1220'>${escapeText(label||"")}</text></svg>`)}const DEFAULT_ICON_RULES=[{icon:svgDocumentIcon("IMG","#c7ddff"),typeMatch:t=>t.startsWith("image/"),exts:[".png",".jpg",".jpeg",".gif",".webp",".bmp",".svg",".avif"]},{icon:svgDocumentIcon("PDF","#ffd7d7"),typeMatch:t=>"application/pdf"===t,exts:[".pdf"]},{icon:svgDocumentIcon("AUD","#e6dcff"),typeMatch:t=>t.startsWith("audio/"),exts:[".mp3",".wav",".m4a",".flac"]},{icon:svgDocumentIcon("VID","#dff7ff"),typeMatch:t=>t.startsWith("video/"),exts:[".mp4",".mov",".webm",".mkv"]},{icon:svgDocumentIcon("DOC","#dfe6ff"),typeMatch:t=>["application/msword","application/vnd.openxmlformats-officedocument.wordprocessingml.document"].includes(t),exts:[".doc",".docx",".odt"]},{icon:svgDocumentIcon("XLS","#e4ffd7"),typeMatch:t=>["text/csv","application/vnd.ms-excel","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"].includes(t),exts:[".xls",".xlsx",".ods",".csv"]},{icon:svgDocumentIcon("ZIP","#fffed7"),typeMatch:t=>t.includes("zip")||"application/x-zip-compressed"===t,exts:[".zip",".tar",".gz"]},{icon:svgDocumentIcon("TXT","#eaeaea"),typeMatch:t=>t.startsWith("text/"),exts:[".txt",".md",".log"]}];export class BrowseJS{constructor(container,files=[],opts={}){if(container instanceof Element)this.container=container;else{const containerElement=document.getElementById(container)||document.querySelector(container);if(!containerElement)throw new Error("Container not found: "+container);this.container=containerElement}this.opts=opts,this.iconRules=opts.icons&&opts.icons.rules?opts.icons.rules:DEFAULT_ICON_RULES,this.folderIcon=opts.icons&&opts.icons.folder?opts.icons.folder:svgFolderIcon(""),this.defaultIcon=opts.icons&&opts.icons.default?opts.icons.default:svgDocumentIcon("?","#e9eefc"),this.multi=Boolean(opts.multiSelect),this.selectedIndices=new Set,this.stack=[{name:opts.rootName||"Root",files:files}],this.breadcrumbEl=document.createElement("nav"),this.breadcrumbEl.className="breadcrumb",this.breadcrumbEl.setAttribute("aria-label","Breadcrumb"),this.crumbsWrap=document.createElement("div"),this.crumbsWrap.className="crumbs-wrap",this.controlsEl=document.createElement("div"),this.controlsEl.className="crumb-controls",this.breadcrumbEl.appendChild(this.crumbsWrap),this.breadcrumbEl.appendChild(this.controlsEl),this.detailsEl=document.createElement("aside"),this.detailsEl.className="details",this.detailsEl.setAttribute("aria-live","polite"),this.detailsEl.textContent=opts.detailsText||"Select a file",this.container.innerHTML="",this.galleryEl=document.createElement("div"),this.galleryEl.className="gallery-grid",this.container.appendChild(this.breadcrumbEl),this.container.appendChild(this.galleryEl),this.container.appendChild(this.detailsEl),this._fileInput=document.createElement("input"),this._fileInput.type="file",this._fileInput.style.display="none",this.container.appendChild(this._fileInput),this.container.classList.add("browsejs"),this.galleryEl.tabIndex=0,document.addEventListener("dragover",e=>{e.preventDefault(),this.container.classList.add("dragover")}),document.addEventListener("dragleave",e=>{this.container.classList.remove("dragover")}),this.container.addEventListener("drop",e=>{e.preventDefault(),this.container.classList.remove("dragover");const files=Array.from(e.dataTransfer&&e.dataTransfer.files||[]);0!==files.length&&this.handleDropFiles(files)}),this.render()}getIconForItem(item){if(item.children)return this.folderIcon;const type=item.meta&&item.meta.type?String(item.meta.type).toLowerCase():"",name=item.name?String(item.name).toLowerCase():"";if(type)for(const r of this.iconRules)if(r.typeMatch&&r.typeMatch(type))return r.icon;for(const r of this.iconRules)if(r.exts)for(const e of r.exts)if(name.endsWith(e))return r.icon;return this.defaultIcon}render(){this.galleryEl.innerHTML="";this.currentFiles().forEach((f,i)=>{const card=document.createElement("button");card.className="card",card.type="button",card.dataset.index=i,card.title=f.name;const img=document.createElement("img");img.alt=f.name||"",img.src=f.thumbnail||this.getIconForItem(f);const meta=document.createElement("div");meta.className="meta",meta.textContent=f.name,card.appendChild(img),card.appendChild(meta),f.children&&Array.isArray(f.children)?(card.addEventListener("click",()=>this.enterFolder(i)),card.addEventListener("keyup",e=>{"Enter"===e.key&&this.enterFolder(i)})):(card.addEventListener("click",()=>this.select(i)),card.addEventListener("keyup",e=>{"Enter"===e.key&&this.select(i)})),this.galleryEl.appendChild(card)}),this.updateSelectionUI(),this.renderBreadcrumb()}updateSelectionUI(){this.galleryEl.querySelectorAll(".card").forEach(c=>{const idx=Number(c.dataset.index);this.selectedIndices.has(idx)?c.classList.add("selected"):c.classList.remove("selected")}),this.renderDetails()}renderDetails(){if(!this.detailsEl)return;const activeList=this.currentFiles();if(0===this.selectedIndices.size)this.detailsEl.innerHTML='<p class="small">No selection</p>';else if(this.selectedIndices.size>1){const indices=Array.from(this.selectedIndices).sort();this.detailsEl.innerHTML="";const header=document.createElement("div");header.innerHTML=`<strong>${indices.length} item${indices.length>1?"s":""} selected</strong>`,this.detailsEl.appendChild(header);const list=document.createElement("div");list.className="small",list.innerHTML=indices.map(i=>`<div>${escapeText(activeList[i]&&activeList[i].name||"Untitled")}</div>`).join(""),this.detailsEl.appendChild(list)}else{const index=Array.from(this.selectedIndices)[0],item=activeList[index];if(!item)return void(this.detailsEl.innerHTML='<p class="small">No selection</p>');this.detailsEl.innerHTML="";const img=document.createElement("img");img.className="preview",img.src=item.thumbnail||this.galleryEl.querySelector(`.card[data-index="${index}"] img`)?.src||this.getIconForItem(item),img.alt=item.name||"preview";const name=document.createElement("div");name.innerHTML=`<strong>${item.name||"Untitled"}</strong>`;const meta=document.createElement("div");meta.className="small",item.meta&&"object"==typeof item.meta?meta.innerHTML=Object.entries(item.meta).map(([k,v])=>`<div><strong>${k}:</strong> ${v}</div>`).join(""):item.meta?meta.textContent=String(item.meta):meta.textContent="",this.detailsEl.appendChild(img),this.detailsEl.appendChild(name),this.detailsEl.appendChild(meta)}}renderBreadcrumb(){if(!this.breadcrumbEl)return;this.crumbsWrap.innerHTML="",this.stack.forEach((s,idx)=>{const btn=document.createElement("button");if(btn.type="button",btn.className="crumb",btn.textContent=s.name,btn.addEventListener("click",()=>this.goToCrumb(idx)),this.crumbsWrap.appendChild(btn),idx<this.stack.length-1){const sep=document.createElement("span");sep.className="sep",sep.textContent="»",this.crumbsWrap.appendChild(sep)}}),this.controlsEl.innerHTML="";const hasCreate="function"==typeof this.opts.onCreateFolder,hasUpload="function"==typeof this.opts.onUpload;if(hasCreate){const createBtn=document.createElement("button");createBtn.type="button",createBtn.className="crumb-action",createBtn.textContent="New Folder",createBtn.addEventListener("click",()=>this.handleCreateFolder()),this.controlsEl.appendChild(createBtn)}if(hasUpload){const uploadBtn=document.createElement("button");uploadBtn.type="button",uploadBtn.className="crumb-action",uploadBtn.textContent="Upload",uploadBtn.addEventListener("click",()=>this.handleUpload()),this.controlsEl.appendChild(uploadBtn)}}currentFolder(){return this.stack.map(s=>s.name+"/").slice(1).join()}currentFiles(){return this.stack[this.stack.length-1].files}addFiles(files){Array.isArray(files)||(files=[files]);this.currentFiles().push(...files),this.render()}getSelectedPaths(){const activeList=this.currentFiles(),basePath=this.currentFolder(),paths=[];return Array.from(this.selectedIndices).forEach(i=>{const item=activeList[i];item&&paths.push(basePath+item.name)}),paths}async handleCreateFolder(){if(this._creatingFolder)return;this._creatingFolder=!0;const current=this.currentFiles(),card=document.createElement("div");card.className="card creating",card.tabIndex=0;const img=document.createElement("img");img.alt="Folder",img.src=this.folderIcon;const meta=document.createElement("div");meta.className="meta";const nameEl=document.createElement("div");nameEl.className="editable-name",nameEl.contentEditable="true",nameEl.spellcheck=!1,nameEl.textContent="",meta.appendChild(nameEl),card.appendChild(img),card.appendChild(meta),this.galleryEl.insertBefore(card,this.galleryEl.firstChild),nameEl.focus();try{const sel=window.getSelection(),range=document.createRange();range.selectNodeContents(nameEl),sel.removeAllRanges(),sel.addRange(range)}catch(e){}const cleanup=()=>{this._creatingFolder=!1,card.parentNode&&card.parentNode.removeChild(card)},commit=async()=>{const name=nameEl.textContent.trim();if(name){if("function"==typeof this.opts.onCreateFolder){const res=await this.opts.onCreateFolder(name);if(!res)return void cleanup();current.splice(0,0,res)}else current.splice(0,0,{name:name,children:[]});this._creatingFolder=!1,this.render()}else cleanup()};nameEl.addEventListener("keydown",e=>{"Enter"===e.key?(e.preventDefault(),nameEl.blur()):"Escape"===e.key&&(e.preventDefault(),cleanup())}),nameEl.addEventListener("blur",()=>{setTimeout(()=>{this._creatingFolder&&commit()},0)},{once:!0})}async handleUpload(){"function"==typeof this.opts.onUpload&&(this._fileInput.value="",this._fileInput.multiple=!0,this._fileInput.onchange=async()=>{const files=Array.from(this._fileInput.files||[]);if(0!==files.length)try{const res=await this.opts.onUpload(files);if(res){const current=this.currentFiles();Array.isArray(res)?current.push(...res):current.push(res),this.render()}}catch(err){console.error("onUpload error",err)}},this._fileInput.click())}async handleDropFiles(files){if(files&&0!==files.length&&"function"==typeof this.opts.onUpload)try{const res=await this.opts.onUpload(files);if(res){const current=this.currentFiles();Array.isArray(res)?current.push(...res):current.push(res),this.render()}}catch(err){console.error("onUpload error",err)}}select(i){const activeList=this.currentFiles();if(this.multi?this.selectedIndices.has(i)?this.selectedIndices.delete(i):this.selectedIndices.add(i):this.selectedIndices.has(i)?this.selectedIndices.clear():(this.selectedIndices.clear(),this.selectedIndices.add(i)),this.updateSelectionUI(),"function"==typeof this.opts.onSelect){const indices=Array.from(this.selectedIndices).sort((a,b)=>a-b),items=indices.map(idx=>activeList[idx]);this.opts.onSelect(items,indices)}}enterFolder(i){const f=this.currentFiles()[i];f&&Array.isArray(f.children)&&(this.stack.push({name:f.name||"Folder",files:f.children}),this.selectedIndices.clear(),this.render())}goToCrumb(idx){this.stack=this.stack.slice(0,idx+1),this.selectedIndices.clear(),this.render()}}

package/dist/style.css

@@ -0,0 +1,111 @@
+.browsejs {
+  --gap: 12px;
+  --selection-color: #2348d6;
+  display: grid;
+  grid-template-columns: 1fr 280px;
+  grid-template-rows: auto 1fr;
+  grid-template-areas: "breadcrumb breadcrumb" "gallery details";
+  gap: var(--gap);
+}
+.browsejs button {
+  font-family: inherit;
+}
+.browsejs .card {
+  background: transparent;
+  border: none;
+  overflow: hidden;
+  cursor: pointer;
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+}
+.browsejs .card img {
+  width: 100%;
+  height: 160px;
+  object-fit: contain;
+  display: block;
+}
+.browsejs .card .meta {
+  padding: 3px;
+  font-size: 13px;
+  color: #0b1220;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.browsejs .card .editable-name {
+  padding: 3px;
+}
+.browsejs .card.selected {
+  border-color: var(--selection-color);
+  box-shadow: 0 6px 18px #2463ff1f;
+}
+.browsejs .gallery-grid {
+  box-sizing: border-box;
+  border: 2px dotted transparent;
+  grid-area: gallery;
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
+  grid-auto-rows: max-content;
+  gap: var(--gap);
+  padding: var(--gap);
+  overflow-y: auto;
+}
+.browsejs .details {
+  background: #fff;
+  border-radius: 8px;
+  padding: var(--gap);
+  min-height: 140px;
+  grid-area: details;
+}
+.browsejs .preview {
+  width: 100%;
+  height: 180px;
+  object-fit: contain;
+  background: #e9eefc;
+  border-radius: 6px;
+  display: block;
+  margin-bottom: 10px;
+}
+.browsejs .small {
+  font-size: 13px;
+  color: #475569;
+}
+.browsejs .breadcrumb {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  justify-content: space-between;
+  margin-top: 8px;
+  grid-area: breadcrumb;
+}
+.browsejs .breadcrumb .crumb {
+  background: transparent;
+  border: 0;
+  padding: 4px 6px;
+  cursor: pointer;
+  color: var(--selection-color);
+}
+.browsejs .breadcrumb .crumb:hover {
+  background: #2463ff0f;
+}
+.browsejs .breadcrumb .sep {
+  color: #94a3b8;
+}
+.browsejs.dragover .gallery-grid {
+  border-color: var(--selection-color);
+}
+.browsejs.dragover .gallery-grid .card {
+  opacity: 0.7;
+}
+@media (max-width: 800px) {
+  .browsejs {
+    padding: 0 10px;
+    grid-template-columns: 1fr;
+    grid-template-rows: auto 1fr max-content;
+    grid-template-areas: "breadcrumb" "gallery" "details";
+  }
+  .browsejs .details {
+    min-height: initial;
+  }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "browse.js",
+  "version": "0.0.1",
+  "description": "A lightweight yet versatile file browser written in vanilla JS.",
+  "keywords": [
+    "file",
+    "browser",
+    "chooser",
+    "widget"
+  ],
+  "homepage": "https://github.com/pydsigner/browse.js#readme",
+  "bugs": {
+    "url": "https://github.com/pydsigner/browse.js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pydsigner/browse.js.git"
+  },
+  "license": "Apache-2.0",
+  "author": "Daniel Foerster <df@d48.io> (https://d48.io)",
+  "type": "commonjs",
+  "main": "dist/browse.js",
+  "scripts": {
+    "build": "tsc && terser src/browse.js -o dist/browse.js && terser src/browse.js -c -o dist/browse.min.js && lessc src/style.less dist/style.css",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "devDependencies": {
+    "less": "^4.5.1",
+    "terser": "^5.46.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/browse.js

@@ -0,0 +1,475 @@
+// Create a data URL from raw SVG markup
+function svgDataUrlFromSvg(svg) {
+    return 'data:image/svg+xml;utf8,' + encodeURIComponent(svg);
+}
+
+function escapeText(t) {
+    return String(t).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+function svgDocumentIcon(label, bg = '#e9eefc', w = 240, h = 310) {
+    const safe = escapeText(label || '');
+    const fold = 84;
+
+    // Draw page body leaving out the folded corner area
+    const bodyPath = `M0 0 H${w - fold} L${w} ${fold} V${h} H0 Z`;
+    // Draw the folded corner as a darker layer on top
+    const foldPath = `M${w - fold} 0 v${fold} h${fold} Z`;
+
+    const svg = `<?xml version='1.0' encoding='utf-8'?><svg xmlns='http://www.w3.org/2000/svg' width='${w}' height='${h}' viewBox='0 0 ${w} ${h}'>` +
+        `<path d='${bodyPath}' fill='${bg}' stroke='#0b12200a' stroke-linejoin='round'/>` +
+        `<path d='${foldPath}' fill='#0000001a' stroke='#0b122005'/>` +
+        `<text x='50%' y='58%' dominant-baseline='middle' text-anchor='middle' font-family='Inter,Arial,Helvetica,sans-serif' font-size='36' fill='#0b1220'>${safe}</text>` +
+        `</svg>`;
+    return svgDataUrlFromSvg(svg);
+}
+
+function svgFolderIcon(label, bg = '#ffd7a8', w = 420, h = 320) {
+    const safe = escapeText(label || '');
+    const tabH = 44;
+    const tabW = 120;
+    const svg = `<?xml version='1.0' encoding='utf-8'?><svg xmlns='http://www.w3.org/2000/svg' width='${w}' height='${h}' viewBox='0 0 ${w} ${h}'>` +
+        `<rect x='6' y='34' rx='12' ry='12' width='${w - 12}' height='${h - 40}' fill='${bg}' stroke='#0b12200a'/>` +
+        `<rect x='18' y='12' rx='8' ry='8' width='${tabW}' height='${tabH}' fill='${bg}'/>` +
+        `<text x='50%' y='62%' dominant-baseline='middle' text-anchor='middle' font-family='Inter,Arial,Helvetica,sans-serif' font-size='36' fill='#0b1220'>${safe}</text>` +
+        `</svg>`;
+    return svgDataUrlFromSvg(svg);
+}
+
+const DEFAULT_ICON_RULES = [
+    { icon: svgDocumentIcon('IMG', '#c7ddff'), typeMatch: t => t.startsWith('image/'), exts: ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.svg', '.avif'] },
+    { icon: svgDocumentIcon('PDF', '#ffd7d7'), typeMatch: t => t === 'application/pdf', exts: ['.pdf'] },
+    { icon: svgDocumentIcon('AUD', '#e6dcff'), typeMatch: t => t.startsWith('audio/'), exts: ['.mp3', '.wav', '.m4a', '.flac'] },
+    { icon: svgDocumentIcon('VID', '#dff7ff'), typeMatch: t => t.startsWith('video/'), exts: ['.mp4', '.mov', '.webm', '.mkv'] },
+    { icon: svgDocumentIcon('DOC', '#dfe6ff'), typeMatch: t => ['application/msword', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'].includes(t), exts: ['.doc', '.docx', '.odt'] },
+    { icon: svgDocumentIcon('XLS', '#e4ffd7'), typeMatch: t => ['text/csv', 'application/vnd.ms-excel', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'].includes(t), exts: ['.xls', '.xlsx', '.ods', '.csv'] },
+    { icon: svgDocumentIcon('ZIP', '#fffed7'), typeMatch: t => t.includes('zip') || t === 'application/x-zip-compressed', exts: ['.zip', '.tar', '.gz'] },
+    { icon: svgDocumentIcon('TXT', '#eaeaea'), typeMatch: t => t.startsWith('text/'), exts: ['.txt', '.md', '.log'] },
+];
+
+
+/**
+ * @typedef {Object} IconRule
+ * @property {string} icon - The icon URL
+ * @property {function(string):boolean} [typeMatch] - Optional function to match against the MIME type of a file
+ * @property {string[]} [exts] - Optional array of file extensions (with dot) to match against the file name
+ */
+
+/**
+ * @typedef {Object} FileItem
+ * @property {string} name - The display name of the file or folder
+ * @property {string} [thumbnail] - Optional data URL for the thumbnail image
+ * @property {Object} [meta] - Optional metadata object with additional info (e.g. size, type)
+ * @property {FileItem[]} [children] - If present, indicates this item is a folder containing these child items
+ */
+
+/**
+ * @typedef {Object} BrowseJSOptions
+ * @property {string} [rootName] - The display name for the root folder (default: "Root")
+ * @property {function(FileItem, number):void} [onSelect] - Callback when a file is selected, receives the file item and its index
+ * @property {string} [detailsText] - Default text to show in the details pane when no selection is made (default: "Select a file")
+ * @property {Object} [icons] - Custom icons configuration
+ * @property {IconRule[]} [icons.rules] - Custom rules for determining icons based on MIME type or file extension
+ * @property {string} [icons.folder] - Custom icon URL for folders
+ * @property {string} [icons.default] - Custom icon URL for files that don't match any rule
+ * @property {boolean} [multiSelect] - If true, allows selecting multiple files (default: false)
+ * @property {function(string):?(FileItem)} [onCreateFolder] - Optional callback invoked when creating a new folder. If it returns a FileItem, it will be added to the current folder.
+ * @property {function(File[]):?(FileItem|FileItem[])} [onUpload] - Optional callback invoked when files are uploaded. If it returns FileItem(s), they'll be added to the current folder.
+ */
+
+export class BrowseJS {
+    /**
+     * @param {string|Element} container - The the container element to render the gallery into. Can be a DOM element, ID, or selector string.
+     * @param {FileItem[]} files - An array of file items to display in the root folder
+     * @param {BrowseJSOptions} opts - Configuration options (see BrowseJSOptions typedef for details)
+     */
+    constructor(container, files = [], opts = {}) {
+        if (container instanceof Element) { this.container = container; }
+        else {
+            const containerElement = document.getElementById(container) || document.querySelector(container);
+            if (!containerElement) throw new Error('Container not found: ' + container);
+            this.container = containerElement;
+        }
+        this.opts = opts;
+        this.iconRules = opts.icons && opts.icons.rules ? opts.icons.rules : DEFAULT_ICON_RULES;
+        this.folderIcon = opts.icons && opts.icons.folder ? opts.icons.folder : svgFolderIcon('');
+        this.defaultIcon = opts.icons && opts.icons.default ? opts.icons.default : svgDocumentIcon('?', '#e9eefc');
+        this.multi = Boolean(opts.multiSelect);
+        this.selectedIndices = new Set();
+        this.stack = [{ name: opts.rootName || 'Root', files }];
+
+        // create breadcrumb and details elements and insert around the gallery container
+        this.breadcrumbEl = document.createElement('nav');
+        this.breadcrumbEl.className = 'breadcrumb';
+        this.breadcrumbEl.setAttribute('aria-label', 'Breadcrumb');
+
+        // crumbs wrapper and controls container
+        this.crumbsWrap = document.createElement('div');
+        this.crumbsWrap.className = 'crumbs-wrap';
+        this.controlsEl = document.createElement('div');
+        this.controlsEl.className = 'crumb-controls';
+        this.breadcrumbEl.appendChild(this.crumbsWrap);
+        this.breadcrumbEl.appendChild(this.controlsEl);
+
+        this.detailsEl = document.createElement('aside');
+        this.detailsEl.className = 'details';
+        this.detailsEl.setAttribute('aria-live', 'polite');
+        this.detailsEl.textContent = opts.detailsText || 'Select a file';
+
+        // Insert breadcrumb, gallery grid and details inside the gallery container
+        this.container.innerHTML = '';
+        this.galleryEl = document.createElement('div');
+        this.galleryEl.className = 'gallery-grid';
+        this.container.appendChild(this.breadcrumbEl);
+        this.container.appendChild(this.galleryEl);
+        this.container.appendChild(this.detailsEl);
+
+        this._fileInput = document.createElement('input');
+        this._fileInput.type = 'file';
+        this._fileInput.style.display = 'none';
+        this.container.appendChild(this._fileInput);
+
+        // bind events to the inner gallery grid
+        this.container.classList.add('browsejs');
+        this.galleryEl.tabIndex = 0;
+
+        // drag & drop support: highlight container on dragover, accept drops
+        document.addEventListener('dragover', (e) => {
+            e.preventDefault();
+            this.container.classList.add('dragover');
+        });
+        document.addEventListener('dragleave', (e) => {
+            this.container.classList.remove('dragover');
+        });
+        this.container.addEventListener('drop', (e) => {
+            e.preventDefault();
+            this.container.classList.remove('dragover');
+            const files = Array.from((e.dataTransfer && e.dataTransfer.files) || []);
+            if (files.length === 0) return;
+            this.handleDropFiles(files);
+        });
+
+        this.render();
+    }
+
+    getIconForItem(item) {
+        if (item.children) return this.folderIcon;
+        const type = item.meta && item.meta.type ? String(item.meta.type).toLowerCase() : '';
+        const name = item.name ? String(item.name).toLowerCase() : '';
+
+        if (type) {
+            for (const r of this.iconRules) {
+                if (r.typeMatch && r.typeMatch(type)) return r.icon;
+            }
+        }
+        for (const r of this.iconRules) {
+            if (r.exts) {
+                for (const e of r.exts) {
+                    if (name.endsWith(e)) return r.icon;
+                }
+            }
+        }
+        return this.defaultIcon;
+    }
+
+    render() {
+        this.galleryEl.innerHTML = '';
+        const list = this.currentFiles();
+        list.forEach((f, i) => {
+            const card = document.createElement('button');
+            card.className = 'card';
+            card.type = 'button';
+            card.dataset.index = i;
+            card.title = f.name;
+
+            const img = document.createElement('img');
+            img.alt = f.name || '';
+            img.src = f.thumbnail || this.getIconForItem(f);
+
+            const meta = document.createElement('div');
+            meta.className = 'meta';
+            meta.textContent = f.name;
+
+            card.appendChild(img);
+            card.appendChild(meta);
+
+            if (f.children && Array.isArray(f.children)) {
+                card.addEventListener('click', () => this.enterFolder(i));
+                card.addEventListener('keyup', (e) => { if (e.key === 'Enter') this.enterFolder(i); });
+            } else {
+                card.addEventListener('click', () => this.select(i));
+                card.addEventListener('keyup', (e) => { if (e.key === 'Enter') this.select(i); });
+            }
+
+            this.galleryEl.appendChild(card);
+        });
+        this.updateSelectionUI();
+        this.renderBreadcrumb();
+    }
+
+    updateSelectionUI() {
+        const cards = this.galleryEl.querySelectorAll('.card');
+        cards.forEach(c => {
+            const idx = Number(c.dataset.index);
+            if (this.selectedIndices.has(idx)) c.classList.add('selected');
+            else c.classList.remove('selected');
+        });
+        this.renderDetails();
+    }
+
+    renderDetails() {
+        if (!this.detailsEl) return;
+        const activeList = this.currentFiles();
+        if (this.selectedIndices.size === 0) { this.detailsEl.innerHTML = '<p class="small">No selection</p>'; }
+        // If multiple selected, show a simple list and count
+        else if (this.selectedIndices.size > 1) {
+            const indices = Array.from(this.selectedIndices).sort();
+            this.detailsEl.innerHTML = '';
+            const header = document.createElement('div');
+            header.innerHTML = `<strong>${indices.length} item${indices.length > 1 ? 's' : ''} selected</strong>`;
+            this.detailsEl.appendChild(header);
+            const list = document.createElement('div');
+            list.className = 'small';
+            list.innerHTML = indices.map(i => `<div>${escapeText((activeList[i] && activeList[i].name) || 'Untitled')}</div>`).join('');
+            this.detailsEl.appendChild(list);
+        }
+        else {
+            const index = Array.from(this.selectedIndices)[0];
+            const item = activeList[index];
+            if (!item) { this.detailsEl.innerHTML = '<p class="small">No selection</p>'; return; }
+            this.detailsEl.innerHTML = '';
+            const img = document.createElement('img');
+            img.className = 'preview';
+            img.src = item.thumbnail || this.galleryEl.querySelector(`.card[data-index="${index}"] img`)?.src || this.getIconForItem(item);
+            img.alt = item.name || 'preview';
+            const name = document.createElement('div');
+            name.innerHTML = `<strong>${item.name || 'Untitled'}</strong>`;
+            const meta = document.createElement('div');
+            meta.className = 'small';
+
+            if (item.meta && typeof item.meta === 'object') {
+                meta.innerHTML = Object.entries(item.meta).map(([k, v]) => `<div><strong>${k}:</strong> ${v}</div>`).join('');
+            } else if (item.meta) {
+                meta.textContent = String(item.meta);
+            } else {
+                meta.textContent = '';
+            }
+
+            this.detailsEl.appendChild(img);
+            this.detailsEl.appendChild(name);
+            this.detailsEl.appendChild(meta);
+        }
+    }
+
+    renderBreadcrumb() {
+        if (!this.breadcrumbEl) return;
+        this.crumbsWrap.innerHTML = '';
+        this.stack.forEach((s, idx) => {
+            const btn = document.createElement('button');
+            btn.type = 'button';
+            btn.className = 'crumb';
+            btn.textContent = s.name;
+            btn.addEventListener('click', () => this.goToCrumb(idx));
+            this.crumbsWrap.appendChild(btn);
+            if (idx < this.stack.length - 1) {
+                const sep = document.createElement('span'); sep.className = 'sep'; sep.textContent = '»';
+                this.crumbsWrap.appendChild(sep);
+            }
+        });
+
+        this.controlsEl.innerHTML = '';
+        const hasCreate = typeof this.opts.onCreateFolder === 'function';
+        const hasUpload = typeof this.opts.onUpload === 'function';
+        if (hasCreate) {
+            const createBtn = document.createElement('button');
+            createBtn.type = 'button';
+            createBtn.className = 'crumb-action';
+            createBtn.textContent = 'New Folder';
+            createBtn.addEventListener('click', () => this.handleCreateFolder());
+            this.controlsEl.appendChild(createBtn);
+        }
+
+        if (hasUpload) {
+            const uploadBtn = document.createElement('button');
+            uploadBtn.type = 'button';
+            uploadBtn.className = 'crumb-action';
+            uploadBtn.textContent = 'Upload';
+            uploadBtn.addEventListener('click', () => this.handleUpload());
+            this.controlsEl.appendChild(uploadBtn);
+        }
+    }
+
+    currentFolder() {return this.stack.map(s => s.name + '/').slice(1).join();}
+
+    currentFiles() { return this.stack[this.stack.length - 1].files; }
+
+    addFiles(files) {
+        if (!Array.isArray(files)) files = [files];
+        const current = this.currentFiles();
+        current.push(...files);
+        this.render();
+    }
+
+    getSelectedPaths() {
+        const activeList = this.currentFiles();
+        const basePath = this.currentFolder();
+        const paths = [];
+        Array.from(this.selectedIndices).forEach(i => {
+            const item = activeList[i];
+            if (item) {
+                paths.push(basePath + item.name);
+            }
+        });
+        return paths;
+    }
+
+    async handleCreateFolder() {
+        if (this._creatingFolder) return;
+        this._creatingFolder = true;
+
+        const current = this.currentFiles();
+
+        const card = document.createElement('div');
+        card.className = 'card creating';
+        card.tabIndex = 0;
+
+        const img = document.createElement('img');
+        img.alt = 'Folder';
+        img.src = this.folderIcon;
+
+        const meta = document.createElement('div');
+        meta.className = 'meta';
+
+        const nameEl = document.createElement('div');
+        nameEl.className = 'editable-name';
+        nameEl.contentEditable = 'true';
+        nameEl.spellcheck = false;
+        nameEl.textContent = '';
+
+        meta.appendChild(nameEl);
+        card.appendChild(img);
+        card.appendChild(meta);
+
+        this.galleryEl.insertBefore(card, this.galleryEl.firstChild);
+
+        // focus and select text
+        nameEl.focus();
+        try {
+            const sel = window.getSelection();
+            const range = document.createRange();
+            range.selectNodeContents(nameEl);
+            sel.removeAllRanges();
+            sel.addRange(range);
+        } catch (e) { /* ignore selection errors */ }
+
+        const cleanup = () => {
+            this._creatingFolder = false;
+            if (card.parentNode) card.parentNode.removeChild(card);
+        };
+
+        const commit = async () => {
+            const name = nameEl.textContent.trim();
+            if (!name) { cleanup(); return; }
+            if (typeof this.opts.onCreateFolder === 'function') {
+                const res = await this.opts.onCreateFolder(name);
+                if (res) { current.splice(0, 0, res); }
+                else { cleanup(); return; }
+            } else {
+                current.splice(0, 0, { name, children: [] });
+            }
+            this._creatingFolder = false;
+            this.render();
+        };
+
+        const onKey = (e) => {
+            if (e.key === 'Enter') {
+                e.preventDefault();
+                nameEl.blur();
+            } else if (e.key === 'Escape') {
+                e.preventDefault();
+                cleanup();
+            }
+        };
+
+        nameEl.addEventListener('keydown', onKey);
+        nameEl.addEventListener('blur', () => {
+            // commit on blur (allow Enter's blur to fire first)
+            setTimeout(() => {
+                if (!this._creatingFolder) return;
+                commit();
+            }, 0);
+        }, { once: true });
+    }
+
+    async handleUpload() {
+        if (typeof this.opts.onUpload !== 'function') return;
+        this._fileInput.value = '';
+        this._fileInput.multiple = true;
+        this._fileInput.onchange = async () => {
+            const files = Array.from(this._fileInput.files || []);
+            if (files.length === 0) return;
+            try {
+                const res = await this.opts.onUpload(files);
+                if (res) {
+                    const current = this.currentFiles();
+                    if (Array.isArray(res)) current.push(...res); else current.push(res);
+                    this.render();
+                }
+            } catch (err) { console.error('onUpload error', err); }
+        };
+        this._fileInput.click();
+    }
+
+    async handleDropFiles(files) {
+        if (!files || files.length === 0) return;
+        if (typeof this.opts.onUpload !== 'function') return;
+        try {
+            const res = await this.opts.onUpload(files);
+            if (res) {
+                const current = this.currentFiles();
+                if (Array.isArray(res)) current.push(...res); else current.push(res);
+                this.render();
+            }
+        } catch (err) { console.error('onUpload error', err); }
+    }
+
+    select(i) {
+        const activeList = this.currentFiles();
+        if (this.multi) {
+            if (this.selectedIndices.has(i)) {
+                this.selectedIndices.delete(i);
+            }
+            else {
+                this.selectedIndices.add(i);
+            }
+        } else {
+            if (this.selectedIndices.has(i)) {
+                this.selectedIndices.clear();
+            }
+            else {
+                this.selectedIndices.clear();
+                this.selectedIndices.add(i);
+            }
+        }
+        this.updateSelectionUI();
+        if (typeof this.opts.onSelect === 'function') {
+            const indices = Array.from(this.selectedIndices).sort((a, b) => a - b);
+            const items = indices.map(idx => activeList[idx]);
+            this.opts.onSelect(items, indices);
+        }
+    }
+
+    enterFolder(i) {
+        const f = this.currentFiles()[i];
+        if (!f || !Array.isArray(f.children)) return;
+        this.stack.push({ name: f.name || 'Folder', files: f.children });
+        this.selectedIndices.clear();
+        this.render();
+    }
+
+    goToCrumb(idx) {
+        this.stack = this.stack.slice(0, idx + 1);
+        this.selectedIndices.clear();
+        this.render();
+    }
+}

package/src/style.less

@@ -0,0 +1,124 @@
+.browsejs {
+    --gap: 12px;
+    --selection-color: #2348d6;
+    display: grid;
+    grid-template-columns: 1fr 280px;
+    grid-template-rows: auto 1fr;
+    grid-template-areas: "breadcrumb breadcrumb" "gallery details";
+    gap: var(--gap);
+
+    button {
+        font-family: inherit;
+    }
+
+    .card {
+        background: transparent;
+        border: none;
+        overflow: hidden;
+        cursor: pointer;
+        display: flex;
+        flex-direction: column;
+        align-items: stretch;
+
+        img {
+            width: 100%;
+            height: 160px;
+            object-fit: contain;
+            display: block;
+        }
+        .meta {
+            padding: 3px;
+            font-size: 13px;
+            color: #0b1220;
+            white-space: nowrap;
+            overflow: hidden;
+            text-overflow: ellipsis;
+        }
+
+        .editable-name {
+            padding: 3px;
+        }
+
+        &.selected {
+            border-color: var(--selection-color);
+            box-shadow: 0 6px 18px #2463ff1f;
+        }
+    }
+
+    .gallery-grid {
+        box-sizing: border-box;
+        border: 2px dotted transparent;
+        grid-area: gallery;
+        display: grid;
+        grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
+        grid-auto-rows: max-content;
+        gap: var(--gap);
+        padding: var(--gap);
+        overflow-y: auto;
+    }
+
+    .details {
+        background: #fff;
+        border-radius: 8px;
+        padding: var(--gap);
+        min-height: 140px;
+        grid-area: details;
+    }
+
+    .preview {
+        width: 100%;
+        height: 180px;
+        object-fit: contain;
+        background: #e9eefc;
+        border-radius: 6px;
+        display: block;
+        margin-bottom: 10px;
+    }
+
+    .small {
+        font-size: 13px;
+        color: #475569;
+    }
+
+    .breadcrumb {
+        display: flex;
+        gap: 8px;
+        align-items: center;
+        justify-content: space-between;
+        margin-top: 8px;
+        grid-area: breadcrumb;
+
+        .crumb {
+            background: transparent;
+            border: 0;
+            padding: 4px 6px;
+            cursor: pointer;
+            color: var(--selection-color);
+
+            &:hover {
+                background: #2463ff0f;
+            }
+        }
+        .sep {
+            color: #94a3b8;
+        }
+    }
+
+    &.dragover .gallery-grid {
+        border-color: var(--selection-color);
+        .card {
+            opacity: 0.7;
+        }
+    }
+
+    @media (max-width: 800px) {
+        padding: 0 10px;
+        grid-template-columns: 1fr;
+        grid-template-rows: auto 1fr max-content;
+        grid-template-areas: "breadcrumb" "gallery" "details";
+
+        .details {
+            min-height: initial;
+        }
+    }
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "include": ["src/**/*"],
+  "compilerOptions": {
+    "allowJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "outDir": "dist"
+  }
+}