sh3-core 0.19.3 → 0.19.6

package/dist/primitives/widgets/DocumentSaver.svelte.d.ts

@@ -0,0 +1,17 @@
+import type { CommitOnlyEvents } from './_contract';
+import type { DocumentMeta } from '../../documents/types';
+import type { SaverValue } from './DocumentFilePicker';
+type DocListFn = () => Promise<Array<DocumentMeta & {
+    shardId: string;
+}>>;
+type $$ComponentProps = {
+    value?: SaverValue;
+    listDocuments: DocListFn;
+    disabled?: boolean;
+    invalid?: boolean;
+    size?: 'sm' | 'md';
+    buttonLabel?: string;
+} & CommitOnlyEvents<SaverValue>;
+declare const DocumentSaver: import("svelte").Component<$$ComponentProps, {}, "value">;
+type DocumentSaver = ReturnType<typeof DocumentSaver>;
+export default DocumentSaver;

package/dist/primitives/widgets/_DocumentBrowser.svelte

@@ -0,0 +1,339 @@
+<script lang="ts">
+  import {
+    buildTree,
+    formatSize,
+    formatDate,
+    iconForFile,
+    breadcrumbSegments,
+    type DocEntry,
+    type OpenerValue,
+    type SaverValue,
+    type FileItem,
+  } from './DocumentFilePicker';
+
+  let {
+    mode,
+    docs,
+    onCommit,
+    onCancel,
+    close,
+    suggestedName = '',
+  }: {
+    mode: 'open' | 'save';
+    docs: DocEntry[];
+    onCommit: (value: OpenerValue | SaverValue) => void;
+    onCancel: () => void;
+    close: () => void;
+    suggestedName?: string;
+  } = $props();
+
+  let shardId = $state<string | null>(null);
+  let prefix = $state('');
+  let selectedFile = $state<DocEntry | null>(null);
+  let filename = $state(suggestedName);
+  let activeIdx = $state(0);
+  let listEl = $state<HTMLElement | undefined>(undefined);
+
+  const items = $derived(buildTree(docs, shardId, prefix));
+  const crumbs = $derived(breadcrumbSegments(shardId, prefix));
+
+  $effect(() => {
+    items;
+    activeIdx = Math.min(activeIdx, items.length - 1);
+  });
+
+  function navigateShard(id: string) {
+    shardId = id;
+    prefix = '';
+    selectedFile = null;
+    filename = '';
+    activeIdx = 0;
+  }
+
+  function navigatePrefix(p: string) {
+    if (shardId === null) {
+      navigateShard(p);
+    } else {
+      prefix = p;
+      selectedFile = null;
+      filename = '';
+      activeIdx = 0;
+    }
+  }
+
+  function selectFile(item: FileItem) {
+    if (item.kind === 'folder') {
+      navigatePrefix(item.fullPath);
+    } else {
+      if (mode === 'open') {
+        selectedFile = item.doc;
+      }
+      if (mode === 'save') {
+        filename = item.name;
+      }
+    }
+  }
+
+  function commit() {
+    if (mode === 'open' && selectedFile) {
+      onCommit({ shardId: selectedFile.shardId, path: selectedFile.path });
+      close();
+    } else if (mode === 'save' && filename.trim() && shardId) {
+      const p = prefix ? `${shardId}/${prefix}/${filename}` : `${shardId}/${filename}`;
+      onCommit(p);
+      close();
+    }
+  }
+
+  function cancel() {
+    onCancel();
+    close();
+  }
+
+  function canCommit(): boolean {
+    if (mode === 'open') return selectedFile !== null;
+    return filename.trim().length > 0 && shardId !== null;
+  }
+
+  function onKey(e: KeyboardEvent) {
+    if (e.target instanceof HTMLInputElement) return;
+    switch (e.key) {
+      case 'ArrowDown':
+        e.preventDefault();
+        activeIdx = Math.min(activeIdx + 1, items.length - 1);
+        break;
+      case 'ArrowUp':
+        e.preventDefault();
+        activeIdx = Math.max(activeIdx - 1, 0);
+        break;
+      case 'Enter':
+        e.preventDefault();
+        if (activeIdx >= 0 && activeIdx < items.length) {
+          selectFile(items[activeIdx]);
+        }
+        break;
+      case 'Escape':
+        e.preventDefault();
+        cancel();
+        break;
+      case 'Backspace':
+        if (prefix) {
+          e.preventDefault();
+          const parts = prefix.split('/');
+          parts.pop();
+          prefix = parts.join('/');
+          activeIdx = 0;
+        } else if (shardId) {
+          e.preventDefault();
+          shardId = null;
+          activeIdx = 0;
+        }
+        break;
+    }
+  }
+
+  function onDblClick(item: FileItem) {
+    if (item.kind === 'folder') {
+      navigatePrefix(item.fullPath);
+    } else if (mode === 'open') {
+      onCommit({ shardId: item.doc.shardId, path: item.doc.path });
+      close();
+    }
+  }
+</script>
+
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div class="sh3-doc-browser" onkeydown={onKey} tabindex="-1">
+  <div class="sh3-doc-browser__head">
+    <span class="sh3-doc-browser__title">
+      {mode === 'open' ? 'Open Document' : 'Save Document'}
+    </span>
+  </div>
+
+  <nav class="sh3-doc-browser__crumbs">
+    {#each crumbs as seg, i}
+      {#if i > 0}<span class="sh3-doc-browser__crumb-sep">/</span>{/if}
+      <button
+        type="button"
+        class="sh3-doc-browser__crumb"
+        class:sh3-doc-browser__crumb--last={i === crumbs.length - 1}
+        onclick={() => {
+          shardId = seg.targetShard;
+          prefix = seg.targetPrefix;
+          selectedFile = null;
+          filename = '';
+          activeIdx = 0;
+        }}
+      >{seg.label}</button>
+    {/each}
+  </nav>
+
+  <div class="sh3-doc-browser__list" bind:this={listEl}>
+    {#if items.length === 0}
+      <div class="sh3-doc-browser__empty">
+        {shardId === null ? 'No shards available.' : prefix ? 'Empty directory.' : 'No documents in this shard.'}
+      </div>
+    {:else}
+      {#each items as item, i}
+        {@const isActive = i === activeIdx}
+        {@const isSelected = item.kind === 'file' && mode === 'open' && selectedFile?.path === item.doc.path && selectedFile?.shardId === item.doc.shardId}
+        <!-- svelte-ignore a11y_no_static_element_interactions -->
+        <div
+          class="sh3-doc-browser__item"
+          class:sh3-doc-browser__item--active={isActive}
+          class:sh3-doc-browser__item--selected={isSelected}
+          class:sh3-doc-browser__item--folder={item.kind === 'folder'}
+          role="option"
+          tabindex="-1"
+          aria-selected={isSelected}
+          onclick={() => selectFile(item)}
+          onkeydown={(e) => { if (e.key === 'Enter') selectFile(item); }}
+          ondblclick={() => onDblClick(item)}
+          onmouseenter={() => activeIdx = i}
+        >
+          {#if item.kind === 'folder'}
+            <span class="sh3-doc-browser__icon sh3-doc-browser__icon--folder" aria-hidden="true">📁</span>
+            <span class="sh3-doc-browser__name">{item.name}</span>
+            <span class="sh3-doc-browser__meta"></span>
+          {:else}
+            <span class="sh3-doc-browser__icon" aria-hidden="true">{iconForFile(item.name)}</span>
+            <span class="sh3-doc-browser__name">{item.name}</span>
+            <span class="sh3-doc-browser__meta">
+              {formatSize(item.doc.size)}
+              <span class="sh3-doc-browser__date">{formatDate(item.doc.lastModified)}</span>
+            </span>
+          {/if}
+        </div>
+      {/each}
+    {/if}
+  </div>
+
+  {#if mode === 'save' && shardId !== null}
+    <div class="sh3-doc-browser__save-row">
+      <span class="sh3-doc-browser__save-label">Filename:</span>
+      <input
+        class="sh3-doc-browser__save-input"
+        type="text"
+        placeholder="filename.ext"
+        bind:value={filename}
+        onkeydown={(e) => { if (e.key === 'Enter' && canCommit()) commit(); }}
+      />
+    </div>
+  {/if}
+
+  <div class="sh3-doc-browser__footer">
+    <button type="button" class="sh3-doc-browser__btn sh3-doc-browser__btn--cancel" onclick={cancel}>Cancel</button>
+    <button
+      type="button"
+      class="sh3-doc-browser__btn sh3-doc-browser__btn--primary"
+      disabled={!canCommit()}
+      onclick={commit}
+    >
+      {mode === 'open' ? 'Open' : 'Save'}
+    </button>
+  </div>
+</div>
+
+<style>
+  .sh3-doc-browser {
+    background: var(--sh3-bg-elevated);
+    border: 1px solid var(--sh3-border-strong);
+    border-radius: var(--sh3-widget-radius);
+    box-shadow: var(--sh3-shadow-lg);
+    width: 420px;
+    max-height: 480px;
+    display: flex; flex-direction: column;
+    overflow: hidden;
+    color: var(--sh3-fg);
+    font-size: 0.8125rem;
+    outline: none;
+  }
+  .sh3-doc-browser__head {
+    display: flex; align-items: center; justify-content: space-between;
+    padding: 8px 12px;
+    border-bottom: 1px solid var(--sh3-border);
+  }
+  .sh3-doc-browser__title { font-weight: 600; }
+  .sh3-doc-browser__crumbs {
+    display: flex; align-items: center; gap: 2px;
+    padding: 4px 8px;
+    border-bottom: 1px solid var(--sh3-border);
+    overflow-x: auto;
+    flex-shrink: 0;
+  }
+  .sh3-doc-browser__crumb {
+    display: inline-flex; align-items: center;
+    padding: 1px 4px;
+    border: none; background: none;
+    color: var(--sh3-fg-muted);
+    font: inherit; font-size: 0.75rem;
+    cursor: pointer;
+    border-radius: var(--sh3-radius-sm);
+    white-space: nowrap;
+    flex-shrink: 0;
+  }
+  .sh3-doc-browser__crumb:hover { background: var(--sh3-bg); color: var(--sh3-fg); }
+  .sh3-doc-browser__crumb--last { color: var(--sh3-fg); font-weight: 600; }
+  .sh3-doc-browser__crumb-sep { color: var(--sh3-fg-subtle); font-size: 0.75rem; flex-shrink: 0; }
+  .sh3-doc-browser__list { flex: 1; overflow-y: auto; padding: 4px 0; min-height: 0; }
+  .sh3-doc-browser__item { display: flex; align-items: center; gap: 8px; padding: 5px 12px; cursor: pointer; }
+  .sh3-doc-browser__item--active { background: var(--sh3-bg); }
+  .sh3-doc-browser__item--selected { background: var(--sh3-accent); color: var(--sh3-fg-on-accent); }
+  .sh3-doc-browser__item--active.sh3-doc-browser__item--selected { background: var(--sh3-accent); }
+  .sh3-doc-browser__icon { flex-shrink: 0; width: 18px; text-align: center; font-size: 0.875rem; }
+  .sh3-doc-browser__icon--folder { font-size: 0.75rem; }
+  .sh3-doc-browser__name {
+    flex: 1; min-width: 0;
+    overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+    font-family: var(--sh3-font-mono); font-size: 0.75rem;
+  }
+  .sh3-doc-browser__item--folder .sh3-doc-browser__name { font-family: inherit; font-size: 0.8125rem; }
+  .sh3-doc-browser__meta {
+    display: flex; align-items: center; gap: 10px;
+    flex-shrink: 0; font-size: 0.6875rem; color: var(--sh3-fg-muted);
+  }
+  .sh3-doc-browser__item--selected .sh3-doc-browser__meta { color: var(--sh3-fg-on-accent); opacity: 0.8; }
+  .sh3-doc-browser__date { color: var(--sh3-fg-subtle); }
+  .sh3-doc-browser__item--selected .sh3-doc-browser__date { color: var(--sh3-fg-on-accent); opacity: 0.65; }
+  .sh3-doc-browser__empty { padding: 20px 12px; text-align: center; color: var(--sh3-fg-muted); font-style: italic; }
+  .sh3-doc-browser__save-row {
+    display: flex; align-items: center; gap: 8px;
+    padding: 6px 12px; border-top: 1px solid var(--sh3-border);
+  }
+  .sh3-doc-browser__save-label { font-size: 0.75rem; color: var(--sh3-fg-muted); flex-shrink: 0; }
+  .sh3-doc-browser__save-input {
+    flex: 1;
+    height: var(--sh3-field-height-sm);
+    padding: 0 8px;
+    background: var(--sh3-input-bg);
+    border: 1px solid var(--sh3-border);
+    border-radius: var(--sh3-radius-sm);
+    color: var(--sh3-fg);
+    font: inherit; font-family: var(--sh3-font-mono); font-size: 0.75rem;
+    outline: none;
+  }
+  .sh3-doc-browser__save-input:focus { border-color: var(--sh3-input-border-focus); box-shadow: var(--sh3-focus-ring); }
+  .sh3-doc-browser__footer {
+    display: flex; justify-content: flex-end; gap: 8px;
+    padding: 8px 12px; border-top: 1px solid var(--sh3-border);
+  }
+  .sh3-doc-browser__btn {
+    display: inline-flex; align-items: center;
+    height: 26px; padding: 0 12px;
+    border: 1px solid var(--sh3-border);
+    border-radius: var(--sh3-radius-sm);
+    background: var(--sh3-bg-elevated);
+    color: var(--sh3-fg);
+    font: inherit; font-size: 0.75rem;
+    cursor: pointer;
+  }
+  .sh3-doc-browser__btn:hover { background: var(--sh3-bg); }
+  .sh3-doc-browser__btn--primary {
+    background: var(--sh3-accent);
+    color: var(--sh3-fg-on-accent);
+    border-color: var(--sh3-accent);
+  }
+  .sh3-doc-browser__btn--primary:hover { filter: brightness(1.1); }
+  .sh3-doc-browser__btn--primary:disabled { opacity: 0.5; cursor: not-allowed; }
+  .sh3-doc-browser__btn--primary:disabled:hover { filter: none; }
+</style>

package/dist/primitives/widgets/_DocumentBrowser.svelte.d.ts

@@ -0,0 +1,12 @@
+import { type DocEntry, type OpenerValue, type SaverValue } from './DocumentFilePicker';
+type $$ComponentProps = {
+    mode: 'open' | 'save';
+    docs: DocEntry[];
+    onCommit: (value: OpenerValue | SaverValue) => void;
+    onCancel: () => void;
+    close: () => void;
+    suggestedName?: string;
+};
+declare const DocumentBrowser: import("svelte").Component<$$ComponentProps, {}, "">;
+type DocumentBrowser = ReturnType<typeof DocumentBrowser>;
+export default DocumentBrowser;

package/dist/shards/activate.svelte.js

@@ -28,6 +28,7 @@ import { createZoneManager } from '../state/manage';
 import { PERMISSION_STATE_MANAGE } from '../state/types';
 import { PERMISSION_DOCUMENTS_BROWSE, PERMISSION_DOCUMENTS_READ, PERMISSION_DOCUMENTS_WRITE, } from '../documents/types';
 import { createBrowseCapability } from '../documents/browse';
+import { createDocumentPicker } from '../documents/picker-primitive';
 import { createShardKeysApi } from '../keys/client';
 import { PERMISSION_KEYS_MINT } from '../keys/types';
 import { subscribe } from '../keys/revocation-bus.svelte';
@@ -88,7 +89,7 @@ export function registerShard(shard) {
  * @throws If the shard is not registered, if `shard.activate` throws, or if a manifest view has no factory after activation.
  */
 export async function activateShard(id, opts) {
-    var _a, _b, _c, _d, _e, _f, _g;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
     const shard = registeredShards.get(id);
     if (!shard) {
         throw new Error(`Cannot activate shard "${id}": not registered`);
@@ -143,6 +144,13 @@ export async function activateShard(id, opts) {
             return off;
         },
     };
+    const hasBrowse = (_a = shard.manifest.permissions) === null || _a === void 0 ? void 0 : _a.includes(PERMISSION_DOCUMENTS_BROWSE);
+    const browseCap = hasBrowse
+        ? createBrowseCapability(getTenantId(), getDocumentBackend(), {
+            canRead: (_c = (_b = shard.manifest.permissions) === null || _b === void 0 ? void 0 : _b.includes(PERMISSION_DOCUMENTS_READ)) !== null && _c !== void 0 ? _c : false,
+            canWrite: (_e = (_d = shard.manifest.permissions) === null || _d === void 0 ? void 0 : _d.includes(PERMISSION_DOCUMENTS_WRITE)) !== null && _e !== void 0 ? _e : false,
+        })
+        : undefined;
     const ctx = {
         state: (schema) => sh3.state(id, schema),
         registerView: (viewId, factory) => {
@@ -212,19 +220,20 @@ export async function activateShard(id, opts) {
         get tenantId() {
             return getTenantId();
         },
-        zones: ((_a = shard.manifest.permissions) === null || _a === void 0 ? void 0 : _a.includes(PERMISSION_STATE_MANAGE))
+        zones: ((_f = shard.manifest.permissions) === null || _f === void 0 ? void 0 : _f.includes(PERMISSION_STATE_MANAGE))
             ? createZoneManager()
             : undefined,
-        browse: ((_b = shard.manifest.permissions) === null || _b === void 0 ? void 0 : _b.includes(PERMISSION_DOCUMENTS_BROWSE))
-            ? createBrowseCapability(getTenantId(), getDocumentBackend(), {
-                canRead: shard.manifest.permissions.includes(PERMISSION_DOCUMENTS_READ),
-                canWrite: shard.manifest.permissions.includes(PERMISSION_DOCUMENTS_WRITE),
-            })
-            : undefined,
-        keys: ((_c = shard.manifest.permissions) === null || _c === void 0 ? void 0 : _c.includes(PERMISSION_KEYS_MINT))
+        browse: browseCap,
+        documentPicker: browseCap
+            ? createDocumentPicker(() => browseCap.listDocuments())
+            : createDocumentPicker(async () => {
+                const docs = await getDocumentBackend().list(getTenantId(), id);
+                return docs.map(d => (Object.assign(Object.assign({}, d), { shardId: id })));
+            }),
+        keys: ((_g = shard.manifest.permissions) === null || _g === void 0 ? void 0 : _g.includes(PERMISSION_KEYS_MINT))
             ? createShardKeysApi({
                 shardId: id,
-                shardPermissions: (_d = shard.manifest.permissions) !== null && _d !== void 0 ? _d : [],
+                shardPermissions: (_h = shard.manifest.permissions) !== null && _h !== void 0 ? _h : [],
             })
             : undefined,
         contributions,
@@ -241,7 +250,7 @@ export async function activateShard(id, opts) {
         sh3: makeSh3Api({
             callerKind: 'shard',
             callerShardId: id,
-            zones: ((_e = shard.manifest.permissions) === null || _e === void 0 ? void 0 : _e.includes(PERMISSION_STATE_MANAGE))
+            zones: ((_j = shard.manifest.permissions) === null || _j === void 0 ? void 0 : _j.includes(PERMISSION_STATE_MANAGE))
                 ? createZoneManager()
                 : undefined,
         }),
@@ -290,7 +299,7 @@ export async function activateShard(id, opts) {
             try {
                 void fn();
             }
-            catch (_h) {
+            catch (_m) {
                 // intentionally swallowed: original error is what matters.
             }
         }
@@ -304,7 +313,7 @@ export async function activateShard(id, opts) {
         erroredShards.set(id, {
             id,
             error: err,
-            phase: (_f = opts === null || opts === void 0 ? void 0 : opts.phase) !== null && _f !== void 0 ? _f : 'launch',
+            phase: (_k = opts === null || opts === void 0 ? void 0 : opts.phase) !== null && _k !== void 0 ? _k : 'launch',
             timestamp: Date.now(),
         });
         console.error(`[sh3] Shard "${id}" failed to activate:`, err);
@@ -312,7 +321,7 @@ export async function activateShard(id, opts) {
     }
     // Activation succeeded — clear any prior error record for this shard.
     erroredShards.delete(id);
-    void ((_g = shard.autostart) === null || _g === void 0 ? void 0 : _g.call(shard, ctx));
+    void ((_l = shard.autostart) === null || _l === void 0 ? void 0 : _l.call(shard, ctx));
 }
 /**
  * Deactivate an active shard. Calls `shard.deactivate`, flushes and disposes

package/dist/shards/types.d.ts

@@ -2,6 +2,7 @@ import type { StateZones } from '../state/zones.svelte';
 import type { ZoneSchema, ZoneManager } from '../state/types';
 import type { DocumentHandle, DocumentHandleOptions } from '../documents/types';
 import type { BrowseCapability } from '../documents/browse';
+import type { DocumentPickerApi } from '../documents/picker-api';
 import type { EnvState } from '../env/types';
 import type { Verb } from '../verbs/types';
 import type { Sh3Api } from '../verbs/types';
@@ -287,6 +288,13 @@ export interface ShardContext {
      * owning shard's own `ctx.documents()` handle.
      */
     browse?: BrowseCapability;
+    /**
+     * Programmatic document picker. Opens the DocumentBrowser popup scoped
+     * to this shard's document zone (or wider tree if the shard has the
+     * `documents:browse` permission). Returns the selected document reference
+     * or null if the user cancelled.
+     */
+    documentPicker: DocumentPickerApi;
     /**
      * Mint/list/revoke keys minted by this shard. Only available when the
      * manifest declares the `keys:mint` permission.

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export declare const VERSION = "0.19.3";
+export declare const VERSION = "0.19.6";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export const VERSION = '0.19.3';
+export const VERSION = '0.19.6';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh3-core",
-  "version": "0.19.3",
+  "version": "0.19.6",
   "type": "module",
   "files": [
     "dist"