@walkthru-earth/objex 0.1.0 → 1.1.0

package/dist/utils/clipboard.js

@@ -0,0 +1,38 @@
+import { COPY_FEEDBACK_MS } from '../constants.js';
+/**
+ * Copy text to clipboard and run a feedback callback for COPY_FEEDBACK_MS.
+ * Silently catches clipboard errors (e.g. insecure context).
+ *
+ * @returns true if copy succeeded, false otherwise.
+ */
+export async function copyToClipboard(text, onFeedback) {
+    try {
+        await navigator.clipboard.writeText(text);
+        onFeedback?.(true);
+        setTimeout(() => onFeedback?.(false), COPY_FEEDBACK_MS);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Wire click-to-copy on all elements matching `selector` inside `root`.
+ * Each element must have `data-code` (URI-encoded) with the text to copy.
+ * Adds/removes a `copied` CSS class for visual feedback.
+ */
+export function wireCodeCopyButtons(root, selector) {
+    for (const btn of root.querySelectorAll(selector)) {
+        btn.addEventListener('click', async () => {
+            const code = decodeURIComponent(btn.dataset.code ?? '');
+            try {
+                await navigator.clipboard.writeText(code);
+                btn.classList.add('copied');
+                setTimeout(() => btn.classList.remove('copied'), COPY_FEEDBACK_MS);
+            }
+            catch {
+                // clipboard not available
+            }
+        });
+    }
+}

package/dist/utils/cloud-url.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Cloud storage protocol URL utilities — pure TS, no Svelte dependency.
+ *
+ * Converts cloud protocol URLs (s3://, gs://) to HTTPS URLs for browser access.
+ * Provider-aware native scheme lookup.
+ */
+/**
+ * Map provider to its native URI scheme prefix.
+ * Derived from the registry's `schemes` array (first entry is the primary scheme).
+ * Falls back to 's3' for providers without a scheme (S3-compatible).
+ */
+export declare function getNativeScheme(provider: string): string;
+/**
+ * Safely decode a percent-encoded URI component.
+ * Returns the original string if decoding fails (malformed sequences).
+ */
+export declare function safeDecodeURIComponent(s: string): string;
+/**
+ * Convert a cloud storage protocol URL (s3://, gs://) to an HTTPS URL
+ * for browser access. Returns the original URL if already HTTP(S) or unknown.
+ *
+ * Supported:
+ * - `s3://bucket/key` → `https://s3.{region}.amazonaws.com/{bucket}/{key}`
+ *   (region auto-detected from bucket name when possible)
+ * - `gs://bucket/key` → `https://storage.googleapis.com/{bucket}/{key}`
+ */
+export declare function resolveCloudUrl(url: string): string;

package/dist/utils/cloud-url.js

@@ -0,0 +1,61 @@
+/**
+ * Cloud storage protocol URL utilities — pure TS, no Svelte dependency.
+ *
+ * Converts cloud protocol URLs (s3://, gs://) to HTTPS URLs for browser access.
+ * Provider-aware native scheme lookup.
+ */
+import { buildProviderBaseUrl, PROVIDERS } from '../storage/providers.js';
+/** AWS region pattern — matches prefixes like "us-west-2", "eu-central-1", etc. */
+const AWS_REGION_RE = /^(us|eu|ap|sa|ca|me|af|il)-(north|south|east|west|central|northeast|southeast|northwest|southwest)-\d+/;
+/**
+ * Map provider to its native URI scheme prefix.
+ * Derived from the registry's `schemes` array (first entry is the primary scheme).
+ * Falls back to 's3' for providers without a scheme (S3-compatible).
+ */
+export function getNativeScheme(provider) {
+    const def = PROVIDERS[provider];
+    if (def?.schemes.length)
+        return def.schemes[0];
+    return 's3';
+}
+/**
+ * Safely decode a percent-encoded URI component.
+ * Returns the original string if decoding fails (malformed sequences).
+ */
+export function safeDecodeURIComponent(s) {
+    try {
+        return decodeURIComponent(s);
+    }
+    catch {
+        return s;
+    }
+}
+/**
+ * Convert a cloud storage protocol URL (s3://, gs://) to an HTTPS URL
+ * for browser access. Returns the original URL if already HTTP(S) or unknown.
+ *
+ * Supported:
+ * - `s3://bucket/key` → `https://s3.{region}.amazonaws.com/{bucket}/{key}`
+ *   (region auto-detected from bucket name when possible)
+ * - `gs://bucket/key` → `https://storage.googleapis.com/{bucket}/{key}`
+ */
+export function resolveCloudUrl(url) {
+    // S3 / S3-compatible: s3://, s3a://, s3n://
+    const s3Match = url.match(/^s3[an]?:\/\/([^/]+)\/?(.*)$/);
+    if (s3Match) {
+        const [, bucket, key] = s3Match;
+        // Detect region from bucket name (e.g. "us-west-2.opendata.source.coop")
+        const regionMatch = bucket.match(AWS_REGION_RE);
+        const region = regionMatch ? regionMatch[0] : 'us-east-1';
+        const base = buildProviderBaseUrl('s3', '', bucket, region);
+        return key ? `${base}/${key}` : base;
+    }
+    // Google Cloud Storage: gs://, gcs://
+    const gcsMatch = url.match(/^gcs?:\/\/([^/]+)\/?(.*)$/);
+    if (gcsMatch) {
+        const [, bucket, key] = gcsMatch;
+        const base = buildProviderBaseUrl('gcs', '', bucket, '');
+        return key ? `${base}/${key}` : base;
+    }
+    return url;
+}

package/dist/utils/error.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared error handling for async viewer load operations.
+ */
+/**
+ * Extract an error message from an unknown caught value.
+ * Returns null for AbortError (caller should silently return).
+ */
+export declare function handleLoadError(err: unknown): string | null;

package/dist/utils/error.js

@@ -0,0 +1,12 @@
+/**
+ * Shared error handling for async viewer load operations.
+ */
+/**
+ * Extract an error message from an unknown caught value.
+ * Returns null for AbortError (caller should silently return).
+ */
+export function handleLoadError(err) {
+    if (err instanceof DOMException && err.name === 'AbortError')
+        return null;
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/utils/export.d.ts

@@ -1,2 +1,22 @@
-export declare function exportToCsv(columns: string[], rows: Record<string, any>[], filename: string): void;
-export declare function exportToJson(columns: string[], rows: Record<string, any>[], filename: string): void;
+/**
+ * Escape a CSV field value per RFC 4180.
+ */
+export declare function escapeCsvField(value: string): string;
+/**
+ * Serialize column/row data to a CSV string.
+ * Pure function — no browser APIs, works in Node.js.
+ */
+export declare function serializeToCsv(columns: string[], rows: Record<string, unknown>[]): string;
+/**
+ * Serialize column/row data to a formatted JSON string.
+ * Pure function — no browser APIs, works in Node.js.
+ */
+export declare function serializeToJson(columns: string[], rows: Record<string, unknown>[]): string;
+/**
+ * Export data as CSV file (triggers browser download).
+ */
+export declare function exportToCsv(columns: string[], rows: Record<string, unknown>[], filename: string): void;
+/**
+ * Export data as JSON file (triggers browser download).
+ */
+export declare function exportToJson(columns: string[], rows: Record<string, unknown>[], filename: string): void;

package/dist/utils/export.js

@@ -1,3 +1,4 @@
+import { jsonReplacerBigInt } from './format.js';
 function triggerDownload(content, filename, mimeType) {
     const blob = new Blob([content], { type: mimeType });
     const url = URL.createObjectURL(blob);
@@ -9,30 +10,43 @@ function triggerDownload(content, filename, mimeType) {
     document.body.removeChild(a);
     URL.revokeObjectURL(url);
 }
-function formatValue(value) {
+/** Format a cell value for export (empty string for null/undefined). */
+function formatCellValue(value) {
     if (value === null || value === undefined)
         return '';
     if (value instanceof Date)
         return value.toISOString();
+    if (typeof value === 'bigint')
+        return value.toString();
     if (typeof value === 'object')
-        return JSON.stringify(value);
+        return JSON.stringify(value, jsonReplacerBigInt);
     return String(value);
 }
-function escapeCsvField(value) {
+/**
+ * Escape a CSV field value per RFC 4180.
+ */
+export function escapeCsvField(value) {
     if (value.includes(',') || value.includes('"') || value.includes('\n') || value.includes('\r')) {
         return `"${value.replace(/"/g, '""')}"`;
     }
     return value;
 }
-export function exportToCsv(columns, rows, filename) {
+/**
+ * Serialize column/row data to a CSV string.
+ * Pure function — no browser APIs, works in Node.js.
+ */
+export function serializeToCsv(columns, rows) {
     const header = columns.map(escapeCsvField).join(',');
     const body = rows
-        .map((row) => columns.map((col) => escapeCsvField(formatValue(row[col]))).join(','))
+        .map((row) => columns.map((col) => escapeCsvField(formatCellValue(row[col]))).join(','))
         .join('\n');
-    const csv = `${header}\n${body}`;
-    triggerDownload(csv, filename.endsWith('.csv') ? filename : `${filename}.csv`, 'text/csv;charset=utf-8;');
+    return `${header}\n${body}`;
 }
-export function exportToJson(columns, rows, filename) {
+/**
+ * Serialize column/row data to a formatted JSON string.
+ * Pure function — no browser APIs, works in Node.js.
+ */
+export function serializeToJson(columns, rows) {
     const data = rows.map((row) => {
         const obj = {};
         for (const col of columns) {
@@ -46,6 +60,17 @@ export function exportToJson(columns, rows, filename) {
         }
         return obj;
     });
-    const json = JSON.stringify(data, null, 2);
-    triggerDownload(json, filename.endsWith('.json') ? filename : `${filename}.json`, 'application/json');
+    return JSON.stringify(data, jsonReplacerBigInt, 2);
+}
+/**
+ * Export data as CSV file (triggers browser download).
+ */
+export function exportToCsv(columns, rows, filename) {
+    triggerDownload(serializeToCsv(columns, rows), filename.endsWith('.csv') ? filename : `${filename}.csv`, 'text/csv;charset=utf-8;');
+}
+/**
+ * Export data as JSON file (triggers browser download).
+ */
+export function exportToJson(columns, rows, filename) {
+    triggerDownload(serializeToJson(columns, rows), filename.endsWith('.json') ? filename : `${filename}.json`, 'application/json');
 }

package/dist/utils/file-sort.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Pure file entry sorting — framework-agnostic, works in Node.js.
+ */
+import type { FileEntry } from '../types.js';
+export type SortField = 'name' | 'size' | 'modified' | 'extension';
+export type SortDirection = 'asc' | 'desc';
+export interface SortConfig {
+    field: SortField;
+    direction: SortDirection;
+}
+/**
+ * Sort file entries by the given config.
+ * Directories always sort before files regardless of sort field.
+ * Returns a new array (does not mutate the input).
+ */
+export declare function sortFileEntries(entries: FileEntry[], config: SortConfig): FileEntry[];
+/**
+ * Toggle sort config: same field flips direction, new field starts ascending.
+ */
+export declare function toggleSortField(current: SortConfig, field: SortField): SortConfig;

package/dist/utils/file-sort.js

@@ -0,0 +1,41 @@
+/**
+ * Pure file entry sorting — framework-agnostic, works in Node.js.
+ */
+/**
+ * Sort file entries by the given config.
+ * Directories always sort before files regardless of sort field.
+ * Returns a new array (does not mutate the input).
+ */
+export function sortFileEntries(entries, config) {
+    const sorted = [...entries];
+    const dir = config.direction === 'asc' ? 1 : -1;
+    sorted.sort((a, b) => {
+        // Directories always come first
+        if (a.is_dir && !b.is_dir)
+            return -1;
+        if (!a.is_dir && b.is_dir)
+            return 1;
+        switch (config.field) {
+            case 'name':
+                return dir * a.name.localeCompare(b.name, undefined, { sensitivity: 'base' });
+            case 'size':
+                return dir * (a.size - b.size);
+            case 'modified':
+                return dir * (a.modified - b.modified);
+            case 'extension':
+                return dir * a.extension.localeCompare(b.extension, undefined, { sensitivity: 'base' });
+            default:
+                return 0;
+        }
+    });
+    return sorted;
+}
+/**
+ * Toggle sort config: same field flips direction, new field starts ascending.
+ */
+export function toggleSortField(current, field) {
+    if (current.field === field) {
+        return { field, direction: current.direction === 'asc' ? 'desc' : 'asc' };
+    }
+    return { field, direction: 'asc' };
+}

package/dist/utils/format.d.ts

@@ -12,3 +12,13 @@ export declare function formatDate(timestamp: number): string;
  * Returns an empty string if no extension is found.
  */
 export declare function getFileExtension(filename: string): string;
+/**
+ * JSON replacer that converts BigInt values to strings.
+ * Use with `JSON.stringify(value, jsonReplacerBigInt)`.
+ */
+export declare function jsonReplacerBigInt(_key: string, value: unknown): unknown;
+/**
+ * Format a value for display in tables, attribute panels, and exports.
+ * Handles null, undefined, Date, BigInt, and objects uniformly.
+ */
+export declare function formatValue(value: unknown): string;

package/dist/utils/format.js

@@ -54,3 +54,25 @@ export function getFileExtension(filename) {
         return '';
     return filename.slice(lastDot).toLowerCase();
 }
+/**
+ * JSON replacer that converts BigInt values to strings.
+ * Use with `JSON.stringify(value, jsonReplacerBigInt)`.
+ */
+export function jsonReplacerBigInt(_key, value) {
+    return typeof value === 'bigint' ? value.toString() : value;
+}
+/**
+ * Format a value for display in tables, attribute panels, and exports.
+ * Handles null, undefined, Date, BigInt, and objects uniformly.
+ */
+export function formatValue(value) {
+    if (value === null || value === undefined)
+        return 'NULL';
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (typeof value === 'object')
+        return JSON.stringify(value, jsonReplacerBigInt);
+    return String(value);
+}

package/dist/utils/host-detection.js

@@ -7,6 +7,7 @@
  *
  * Also extracts `rootPrefix` when the app is hosted inside a subfolder.
  */
+import { buildProviderBaseUrl } from '../storage/providers.js';
 import { parseStorageUrl } from './storage-url.js';
 /**
  * Extract root prefix from pathname.
@@ -28,20 +29,8 @@ function extractRootPrefix(pathname) {
 /**
  * Build a normalized API endpoint URL for a detected provider.
  */
-function buildBucketUrl(provider, endpoint, bucket) {
-    if (endpoint) {
-        return `${endpoint.replace(/\/$/, '')}/${bucket}`;
-    }
-    switch (provider) {
-        case 'gcs':
-            return `https://storage.googleapis.com/${bucket}`;
-        case 'azure':
-            return `${endpoint}/${bucket}`;
-        case 'storj':
-            return `https://gateway.storjshare.io/${bucket}`;
-        default:
-            return `https://s3.us-east-1.amazonaws.com/${bucket}`;
-    }
+function buildBucketUrl(provider, endpoint, bucket, region) {
+    return buildProviderBaseUrl((provider === 'unknown' ? 's3' : provider), endpoint, bucket, region || '');
 }
 /**
  * Detect hosting bucket from current URL.
@@ -178,7 +167,7 @@ export function detectHostBucket() {
     const doSpaces = host.match(/^(.+)\.([a-z0-9-]+)\.digitaloceanspaces\.com$/);
     if (doSpaces) {
         return {
-            provider: 's3',
+            provider: 'digitalocean',
             bucket: doSpaces[1],
             region: doSpaces[2],
             endpoint: `https://${doSpaces[2]}.digitaloceanspaces.com`,
@@ -190,7 +179,7 @@ export function detectHostBucket() {
     const doCdn = host.match(/^(.+)\.([a-z0-9-]+)\.cdn\.digitaloceanspaces\.com$/);
     if (doCdn) {
         return {
-            provider: 's3',
+            provider: 'digitalocean',
             bucket: doCdn[1],
             region: doCdn[2],
             endpoint: `https://${doCdn[2]}.digitaloceanspaces.com`,
@@ -204,7 +193,7 @@ export function detectHostBucket() {
         const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
         if (parts.length > 0) {
             return {
-                provider: 's3',
+                provider: 'wasabi',
                 bucket: parts[0],
                 region: wasabi[1],
                 endpoint: `https://${host}`,
@@ -217,7 +206,7 @@ export function detectHostBucket() {
     const b2s3 = host.match(/^(.+)\.s3\.([a-z0-9-]+)\.backblazeb2\.com$/);
     if (b2s3) {
         return {
-            provider: 's3',
+            provider: 'b2',
             bucket: b2s3[1],
             region: b2s3[2],
             endpoint: `https://s3.${b2s3[2]}.backblazeb2.com`,
@@ -267,6 +256,77 @@ export function detectHostBucket() {
             };
         }
     }
+    // Contabo: <region>.contabostorage.com/<bucket>
+    const contabo = host.match(/^([a-z0-9]+)\.contabostorage\.com$/);
+    if (contabo) {
+        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
+        if (parts.length > 0) {
+            return {
+                provider: 'contabo',
+                bucket: parts[0],
+                region: contabo[1],
+                endpoint: `${url.protocol}//${url.host}`,
+                rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
+                bucketUrl: `${url.protocol}//${url.host}/${parts[0]}`
+            };
+        }
+    }
+    // Hetzner: <region>.your-objectstorage.com/<bucket>
+    const hetzner = host.match(/^([a-z0-9]+)\.your-objectstorage\.com$/);
+    if (hetzner) {
+        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
+        if (parts.length > 0) {
+            return {
+                provider: 'hetzner',
+                bucket: parts[0],
+                region: hetzner[1],
+                endpoint: `${url.protocol}//${url.host}`,
+                rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
+                bucketUrl: `${url.protocol}//${url.host}/${parts[0]}`
+            };
+        }
+    }
+    // Linode / Akamai: <bucket>.<region>.linodeobjects.com or <region>.linodeobjects.com/<bucket>
+    const linodeVhost = host.match(/^(.+)\.([a-z0-9-]+)\.linodeobjects\.com$/);
+    if (linodeVhost) {
+        return {
+            provider: 'linode',
+            bucket: linodeVhost[1],
+            region: linodeVhost[2],
+            endpoint: `https://${linodeVhost[2]}.linodeobjects.com`,
+            rootPrefix: extractRootPrefix(pathname),
+            bucketUrl: `https://${linodeVhost[2]}.linodeobjects.com/${linodeVhost[1]}`
+        };
+    }
+    const linodePath = host.match(/^([a-z0-9-]+)\.linodeobjects\.com$/);
+    if (linodePath) {
+        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
+        if (parts.length > 0) {
+            return {
+                provider: 'linode',
+                bucket: parts[0],
+                region: linodePath[1],
+                endpoint: `https://${url.host}`,
+                rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
+                bucketUrl: `https://${url.host}/${parts[0]}`
+            };
+        }
+    }
+    // OVHcloud: s3.<region>.io.cloud.ovh.net/<bucket>
+    const ovh = host.match(/^s3\.([a-z0-9-]+)\.io\.cloud\.ovh\.(?:net|us)$/);
+    if (ovh) {
+        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
+        if (parts.length > 0) {
+            return {
+                provider: 'ovhcloud',
+                bucket: parts[0],
+                region: ovh[1],
+                endpoint: `https://${url.host}`,
+                rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
+                bucketUrl: `https://${url.host}/${parts[0]}`
+            };
+        }
+    }
     // MinIO / localhost / private IPs
     const isLocal = host === 'localhost' ||
         host === '127.0.0.1' ||

package/dist/utils/local-storage.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Generic localStorage helpers with SSR safety.
+ *
+ * Used by connection, settings, and query-history stores to avoid
+ * repeating the same load/persist/try-catch/SSR-guard pattern.
+ */
+/**
+ * Load a JSON value from localStorage.
+ * Returns `defaultValue` on SSR, missing key, or parse error.
+ */
+export declare function loadFromStorage<T>(key: string, defaultValue: T): T;
+/**
+ * Persist a JSON-serializable value to localStorage.
+ * Silently no-ops on SSR or storage errors (quota, private browsing).
+ */
+export declare function persistToStorage(key: string, value: unknown): void;

package/dist/utils/local-storage.js

@@ -0,0 +1,37 @@
+/**
+ * Generic localStorage helpers with SSR safety.
+ *
+ * Used by connection, settings, and query-history stores to avoid
+ * repeating the same load/persist/try-catch/SSR-guard pattern.
+ */
+/**
+ * Load a JSON value from localStorage.
+ * Returns `defaultValue` on SSR, missing key, or parse error.
+ */
+export function loadFromStorage(key, defaultValue) {
+    if (typeof window === 'undefined')
+        return defaultValue;
+    try {
+        const raw = localStorage.getItem(key);
+        if (raw)
+            return JSON.parse(raw);
+    }
+    catch {
+        // ignore parse errors
+    }
+    return defaultValue;
+}
+/**
+ * Persist a JSON-serializable value to localStorage.
+ * Silently no-ops on SSR or storage errors (quota, private browsing).
+ */
+export function persistToStorage(key, value) {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        localStorage.setItem(key, JSON.stringify(value));
+    }
+    catch {
+        // ignore storage errors
+    }
+}

package/dist/utils/notebook.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Lightweight browser-native Jupyter notebook renderer.
+ * Replaces `notebookjs` which depends on jsdom/Buffer (Node.js only).
+ * Handles nbformat 2, 3, 4, and 5.
+ */
+export interface NotebookConfig {
+    markdown: (md: string) => string;
+    ansi: (text: string) => string;
+    highlighter: (code: string, lang: string) => string;
+}
+interface RawNotebook {
+    nbformat: number;
+    nbformat_minor?: number;
+    metadata?: Record<string, any>;
+    cells?: RawCell[];
+    worksheets?: {
+        cells: RawCell[];
+    }[];
+}
+interface RawCell {
+    cell_type: string;
+    source?: string | string[];
+    input?: string | string[];
+    outputs?: RawOutput[];
+    prompt_number?: number;
+    execution_count?: number | null;
+    level?: number;
+    language?: string;
+}
+interface RawOutput {
+    output_type: string;
+    data?: Record<string, string | string[]>;
+    text?: string | string[];
+    stream?: string;
+    name?: string;
+    png?: string;
+    jpeg?: string;
+    svg?: string;
+    html?: string;
+    latex?: string;
+    traceback?: string[];
+    ename?: string;
+    evalue?: string;
+    [key: string]: any;
+}
+export interface NotebookMeta {
+    kernelName: string;
+    language: string;
+    cellCount: number;
+}
+/**
+ * Parse and render a Jupyter notebook JSON to a DOM element.
+ * Returns the rendered element and metadata.
+ */
+export declare function renderNotebook(raw: RawNotebook, config: NotebookConfig): {
+    element: HTMLElement;
+    meta: NotebookMeta;
+};
+export {};