Document and prepare npm package

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: multipleof4

.gitignore

@@ -1,3 +1,4 @@
 dist/
 node_modules/
 *.log
+.npmrc

README.md

@@ -0,0 +1,94 @@
+<p align="center">
+  <img src="docs/ofb.png" width="112" alt="Octopus File Browser logo">
+</p>
+
+# octopus-file-browser
+
+A responsive, framework-free file browser inspired by Gitea. It ships as an accessible Web Component with Material Icon Theme icons and no runtime dependencies.
+
+![Octopus File Browser interface](docs/ui.png)
+
+## Install
+
+```sh
+npm install octopus-file-browser
+```
+
+## Use
+
+```html
+<octopus-file-browser empty-label="No files"></octopus-file-browser>
+
+<script type="module">
+  import 'octopus-file-browser';
+
+  const browser = document.querySelector('octopus-file-browser');
+  browser.entries = [
+    {
+      name: 'src',
+      type: 'directory',
+      modified: '2026-09-23T17:00:00Z',
+      children: [
+        { name: 'app.js', type: 'file', size: 1842, modified: '2026-09-23T17:00:00Z' },
+      ],
+    },
+    { name: 'package.json', type: 'file', size: 986, modified: '2026-09-22T09:30:00Z' },
+  ];
+
+  browser.addEventListener('octopus:open', ({ detail }) => {
+    console.log(detail.path, detail.entry);
+  });
+</script>
+```
+
+Importing the package registers `<octopus-file-browser>`. Directories navigate automatically; selecting a file emits `octopus:open`.
+
+## Entry data
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Displayed filename. |
+| `type` | `"file" \| "directory"` | Entry kind. |
+| `size` | `number` | File size in bytes. |
+| `modified` | `Date \| string \| number` | Modified time. |
+| `children` | `OctopusEntry[]` | Directory contents. |
+| `icon` | `string` | Optional custom icon URL. |
+
+Directories are sorted before files. Names use natural, case-insensitive sorting.
+
+## API
+
+| API | Description |
+| --- | --- |
+| `browser.entries` | Gets or replaces the root entry array and returns to root. |
+| `browser.path` | Current directory path as a new array. |
+| `browser.navigate(path)` | Navigates to a directory path, for example `['src', 'assets']`. |
+| `empty-label` | Attribute controlling the empty-directory message. |
+| `octopus:open` | Event with `{ entry, path }` when a file is selected. |
+| `octopus:navigate` | Event with `{ entries, path }` after navigation. |
+
+The package also exports `OctopusFileBrowser`, `createOctopusFileBrowser`, `sortEntries`, `formatFileSize`, `formatRelativeDate`, `isRecent`, and `fileKindLabel`. Type declarations are included.
+
+## Theme
+
+Set CSS custom properties on the element:
+
+```css
+octopus-file-browser {
+  --ofb-border: #d0d7de;
+  --ofb-text: #181c21;
+  --ofb-muted: #57606a;
+  --ofb-link: #1f2328;
+  --ofb-hover: #f6f8fa;
+  --ofb-focus: #0969da;
+  --ofb-recent: #d15700;
+}
+```
+
+## Repository outputs
+
+- `dist/` contains the publishable ESM and UMD/CJS library builds.
+- `demo/` is the static demo and can be used as a Cloudflare Pages output directory.
+- `npm run check` runs tests and rebuilds both outputs.
+
+See [LICENSE](LICENSE) and [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES).

demo/index.html

@@ -6,7 +6,7 @@
     <meta name="color-scheme" content="light">
     <meta name="theme-color" content="#ffffff">
     <title>octopus-file-browser</title>
-    <script type="module" crossorigin src="/assets/index-DSvdNgV5.js"></script>
+    <script type="module" crossorigin src="/assets/index-DqA94Wnd.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-rQJBLWWV.css">
   </head>
   <body>

octopus-file-browser.d.ts

@@ -0,0 +1,58 @@
+export type OctopusDate = string | number | Date;
+
+export interface OctopusEntry {
+  name: string;
+  type: 'file' | 'directory';
+  size?: number;
+  modified?: OctopusDate;
+  icon?: string;
+  children?: OctopusEntry[];
+}
+
+export interface OctopusOpenDetail {
+  entry: OctopusEntry;
+  path: string[];
+}
+
+export interface OctopusNavigateDetail {
+  entries: OctopusEntry[];
+  path: string[];
+}
+
+export interface OctopusFileBrowserEventMap {
+  'octopus:open': CustomEvent<OctopusOpenDetail>;
+  'octopus:navigate': CustomEvent<OctopusNavigateDetail>;
+}
+
+export class OctopusFileBrowser extends HTMLElement {
+  entries: OctopusEntry[];
+  readonly path: string[];
+  navigate(path?: string[]): void;
+  addEventListener<K extends keyof OctopusFileBrowserEventMap>(
+    type: K,
+    listener: (this: OctopusFileBrowser, event: OctopusFileBrowserEventMap[K]) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject | null,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+}
+
+export function createOctopusFileBrowser(
+  target: Element,
+  options?: { entries?: OctopusEntry[]; emptyLabel?: string },
+): OctopusFileBrowser;
+
+export function fileKindLabel(name?: string): string;
+export function formatFileSize(bytes?: number): string;
+export function formatRelativeDate(value: OctopusDate, now?: number): string;
+export function isRecent(value: OctopusDate, now?: number): boolean;
+export function sortEntries(entries?: OctopusEntry[]): OctopusEntry[];
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'octopus-file-browser': OctopusFileBrowser;
+  }
+}

package-lock.json

@@ -7,12 +7,13 @@
     "": {
       "name": "octopus-file-browser",
       "version": "0.1.0",
-      "license": "UNLICENSED",
-      "dependencies": {
-        "material-icon-theme": "5.38.1"
-      },
+      "license": "SEE LICENSE IN LICENSE",
       "devDependencies": {
+        "material-icon-theme": "5.38.1",
         "vite": "8.3.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/multipleof4"
       }
     },
     "node_modules/@oxc-project/types": {
@@ -309,6 +310,7 @@
       "version": "3.2.0",
       "resolved": "https://registry.npmjs.org/chroma-js/-/chroma-js-3.2.0.tgz",
       "integrity": "sha512-os/OippSlX1RlWWr+QDPcGUZs0uoqr32urfxESG9U93lhUfbnlyckte84Q8P1UQY/qth983AS1JONKmLS4T0nw==",
+      "dev": true,
       "license": "(BSD-3-Clause AND Apache-2.0)"
     },
     "node_modules/detect-libc": {
@@ -631,6 +633,7 @@
       "version": "5.38.1",
       "resolved": "https://registry.npmjs.org/material-icon-theme/-/material-icon-theme-5.38.1.tgz",
       "integrity": "sha512-14cFM4NJGdbuo68rIZTq9TSX0f5BtA6VF+eNX3zq23Z5NoEeVtM4Zn4PpZ0ERl++50jCBrywKFWXmOjbxf0xTA==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "chroma-js": "^3.2.0"

package.json

@@ -5,14 +5,18 @@
   "type": "module",
   "main": "./dist/octopus-file-browser.umd.cjs",
   "module": "./dist/octopus-file-browser.js",
+  "types": "./octopus-file-browser.d.ts",
   "exports": {
     ".": {
+      "types": "./octopus-file-browser.d.ts",
       "import": "./dist/octopus-file-browser.js",
       "require": "./dist/octopus-file-browser.umd.cjs"
     }
   },
   "files": [
     "dist",
+    "octopus-file-browser.d.ts",
+    "LICENSE",
     "THIRD_PARTY_NOTICES"
   ],
   "scripts": {
@@ -30,11 +34,17 @@
     "javascript",
     "gitea"
   ],
-  "license": "UNLICENSED",
-  "dependencies": {
-    "material-icon-theme": "5.38.1"
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/multipleof4/octopus-file-browser.git"
   },
+  "homepage": "https://github.com/multipleof4/octopus-file-browser#readme",
+  "bugs": "https://github.com/multipleof4/octopus-file-browser/issues",
+  "funding": "https://github.com/sponsors/multipleof4",
+  "publishConfig": { "access": "public" },
   "devDependencies": {
+    "material-icon-theme": "5.38.1",
     "vite": "8.3.0"
   }
 }