@pyric/ui/storage

Interfaces

CustomMetadataEntry

One customMetadata row. id is a stable render key — keys are user-editable, so they can’t key the rows themselves.

Properties

DeleteSelectionWithConfirmProps

Properties

DroppedFile

One dropped file, flattened from the drop’s file/folder tree.

Properties

MetadataEditorState

Properties

ObjectBrowserProps

Properties

ObjectInspectorProps

Properties

PathBreadcrumbProps

Properties

StorageDeleteFailure

One entry’s failure in a bulk run. error is the typed StorageError (.code e.g. storage/unauthorized).

Properties

StorageDeleteOutcome

Properties

StorageDeleteProgress

Properties

StorageGateVerdict

Per-path verdict. Upload and delete are evaluated with their granular Storage request methods so request.method policies and missing incoming payload semantics remain truthful. write retains its historical upload meaning; callers use delete for delete affordances.

Properties

StorageListEntry

One row of the merged folder/object model, the prefix→folder synthesis ported (as an idea, not code) from the emulator UI’s useStorageFiles: listAll’s prefixes become kind: 'folder' rows, its items become kind: 'object' rows, folders first.

Properties

StoragePreview

One entry in the content-type preview registry — the storage counterpart of the Firestore field-editor registry, keyed by a match predicate instead of a type name because content types are open-ended. First match wins; consumer previews run BEFORE the built-ins, so overriding image/* is just shipping your own matcher.

Properties

StoragePreviewContext

What a preview’s render receives. blob/blobUrl are only populated for previews that declared needsBlob.

Properties

StorageRecursiveDeleteImpl

Recursive folder delete implementation — the same injection seam as the Firestore half’s RecursiveDeleteImpl. Unlike Firestore (where tree-walking needs sandbox introspection or a Cloud Function), the public storage surface CAN walk a prefix, so the package ships createListAllDeleteImpl as the default; inject your own for server-driven deletes.

Properties

StorageSelectionEntry

What the selection tracks per row — a structural subset of StorageListEntry, so useStorageList’s entries pass straight in. The kind decides the delete verb later (object → deleteObject, folder → recursive).

Properties

UploadDropzoneProps

Properties

UploadEntry

Explicit-path upload input. path is relative to the hook’s path option (the destination folder).

Properties

UploadTask

One file’s upload, TASK-SHAPED for resumable forward-compat: the byte counters and the onProgress callback are in the type NOW so a future uploadBytesResumable-backed implementation emits real intermediate snapshots without a breaking change. Today (pyric/storage has no resumable uploads — COMPAT) a task completes in one tick: onProgress fires once at 0 bytes and once at totalBytes.

Properties

UseMetadataEditorOptions

Properties

UseMetadataEditorResult

Properties

UseObjectUploadOptions

Properties

UseObjectUploadResult

Properties

UsePathStateOptions

Properties

UsePathStateResult

Properties

UseStorageDeleteOptions

Properties

UseStorageDeleteResult

Properties

UseStorageListResult

Properties

UseStorageObjectResult

Properties

UseStorageRulesGateOptions

Properties

UseStorageRulesGateResult

Properties

UseStorageSelectionResult

Properties

Type Aliases

MetadataEditorAction

type MetadataEditorAction =
  | {
  type: "setContentType";
  value: string;
}
  | {
  type: "setCacheControl";
  value: string;
}
  | {
  id: string;
  key: string;
  type: "setCustomKey";
}
  | {
  id: string;
  type: "setCustomValue";
  value: string;
}
  | {
  key?: string;
  type: "addCustomEntry";
  value?: string;
}
  | {
  id: string;
  type: "removeCustomEntry";
}
  | {
  type: "reset";
}
  | {
  type: "commit";
};

Type Declaration

{
  type: "setContentType";
  value: string;
}

type

type: "setContentType";

value

value: string;

{
  type: "setCacheControl";
  value: string;
}

type

type: "setCacheControl";

value

value: string;

{
  id: string;
  key: string;
  type: "setCustomKey";
}

id

id: string;

key

key: string;

type

type: "setCustomKey";

{
  id: string;
  type: "setCustomValue";
  value: string;
}

id

id: string;

type

type: "setCustomValue";

value

value: string;

{
  key?: string;
  type: "addCustomEntry";
  value?: string;
}

key?

optional key: string;

type

type: "addCustomEntry";

value?

optional value: string;

{
  id: string;
  type: "removeCustomEntry";
}

id

id: string;

type

type: "removeCustomEntry";

{
  type: "reset";
}

type

type: "reset";

{
  type: "commit";
}

type

type: "commit";

Internal — a successful save makes the draft the new baseline.

PendingPrefixAction

type PendingPrefixAction =
  | {
  path: string;
  type: "create";
}
  | {
  path: string;
  type: "materialize";
}
  | {
  path: string;
  type: "discard";
}
  | {
  type: "clear";
};

Type Declaration

{
  path: string;
  type: "create";
}

path

path: string;

type

type: "create";

Create a folder at path (absolute, bucket-rooted; nested paths allowed) — adds the full ancestor chain.

{
  path: string;
  type: "materialize";
}

path

path: string;

type

type: "materialize";

An object now exists directly under path: drop path and its ancestors from pending (they are real prefixes now).

{
  path: string;
  type: "discard";
}

path

path: string;

type

type: "discard";

Remove a session-only folder and every pending descendant beneath it.

{
  type: "clear";
}

type

type: "clear";

PendingPrefixState

type PendingPrefixState = readonly string[];

Sorted, deduped, normalized pending prefix paths.

StorageApi

type StorageApi = Pick<pyric-storage-reference-api,
  | "ref"
  | "listAll"
  | "getMetadata"
  | "getBlob"
  | "uploadBytes"
  | "uploadBytesResumable"
| "deleteObject">;

The modular Storage fns the browse/inspect hooks call, as an INJECTABLE bundle (same pattern as @pyric/ui’s FirestoreApi / AuthApi).

Default = in-process pyric/storage, so existing consumers are unchanged. Pyric Studio served mode injects the SharedWorker client bundle so the Storage surface browses the live worker object store. These ops are already async, so no sync/async wrinkle (unlike auth listUsers); the worker handles/refs are runtime-compatible at the surface the hooks use (.fullPath / .name).

uploadBytes rides the same seam so useObjectUpload follows the injected backend: in-process writes are uncapped; the worker client’s uploadBytes (base64 storage.putBytes over the MessagePort) enforces an 8 MiB payload cap on both ends — an over-cap upload fails that file’s task with the typed storage/... too-large error and the rest of the batch proceeds.

NOTE the rules gate (useStorageRulesGate) is NOT here: it reads in-process rules internals and no-ops on a handle without them (worker handles), which is the correct degrade (the worker enforces read rules on listAll server-side).

StorageListStatus

type StorageListStatus = "idle" | "loading" | "success" | "error";

StorageObjectStatus

type StorageObjectStatus = "idle" | "loading" | "success" | "error";

StorageRulesGateStatus

type StorageRulesGateStatus = "idle" | "loading" | "ready" | "error";

StorageRulesSource

type StorageRulesSource = "option" | "sandbox" | "none";

Where the active ruleset came from:

• 'option' — the explicit rules option (string or pre-parsed).
• 'sandbox' — the ruleset deployed on the sandbox handle (getStorageSandbox(ctx, { rules })), read off the handle’s StorageService.
• 'none' — no rules reachable. Every verdict allows (open-by-default, the same semantics pyric/storage’s enforcement layer applies when no rules are configured).

UploadInput

type UploadInput = File | UploadEntry;

upload() accepts plain Files (destination = the file’s webkitRelativePath when present — folder drops keep their structure — else its name) or explicit UploadEntrys.

UploadTaskStatus

type UploadTaskStatus = "running" | "success" | "error";

Variables

defaultStoragePreviews

const defaultStoragePreviews: ReadonlyArray<StoragePreview>;

The section 3 defaults: image, text/json; everything else is metadata-only (the inspector’s data-pyric-preview-none state).

imagePreview

const imagePreview: StoragePreview;

image/* → blob-URL <img>.

initialPendingPrefixes

const initialPendingPrefixes: PendingPrefixState;

TEXT_PREVIEW_MAX_BYTES

const TEXT_PREVIEW_MAX_BYTES: number;

256KB — the section 3 default cap for the text-family preview.

textPreview

const textPreview: StoragePreview;

text/* + application/json → text panel, 256KB cap (bigger objects fall through to the too-large fallback). JSON is pretty-printed when parseable.

Functions

createListAllDeleteImpl()

function createListAllDeleteImpl(api?: Pick<StorageApi, "listAll" | "deleteObject">): StorageRecursiveDeleteImpl;

The default, listAll-driven impl: walks the prefix tree, deleteObjects every item (yielding progress per object), then sweeps each visited folder’s <path>/ placeholder so emptied create-folder folders disappear too (listAll hides placeholders, so the walk alone would leave ghost folders). Placeholder sweeps are best-effort — deletedCount counts listed objects only.

Parameters

Returns

StorageRecursiveDeleteImpl

DeleteSelectionWithConfirm()

function DeleteSelectionWithConfirm(__namedParameters: DeleteSelectionWithConfirmProps): Element;

Bulk delete behind the confirm-dialog primitive, with toasts on outcome — wires useConfirm + useStorageDelete + useToast the way <DeleteWithConfirm> wires the Firestore trio. Requires <ConfirmProvider> AND <ToastProvider> ancestors.

Outcome toasts: all-success → one success toast with the count; any failure → an error toast listing each failed path with its typed StorageError.code.

The default trigger styles via [data-pyric-ui="delete-selection"] (+ [data-pyric-destructive], [data-pyric-running], [data-pyric-denied] with the reason on data-pyric-denied-reason/title); it disables while running, when entries is empty, or when the rules gate denies the selection.

Parameters

Returns

Element

expandPathChain()

function expandPathChain(path: string): string[];

'a/b/c' → ['a', 'a/b', 'a/b/c']; '' → [].

Parameters

Returns

string[]

folderInputError()

function folderInputError(input: string): string;

Validate a create-folder input (relative to the current folder; nested a/b/c allowed — VS Code semantics). Returns an error message or null when valid. Normalization tolerates stray/repeat slashes; ./.. segments are rejected (GCS object names have no dot-segment semantics — accepting them would create unreachable names).

Parameters

Returns

string

initMetadataEditorState()

function initMetadataEditorState(initial: SettableMetadata): MetadataEditorState;

Build the edit state from the metadata a getMetadata / useStorageObject read returned.

Parameters

Returns

MetadataEditorState

isPendingPrefix()

function isPendingPrefix(state: PendingPrefixState, path: string): boolean;

Whether path itself is a pending (session-only) folder.

Parameters

Returns

boolean

metadataEditorReducer()

function metadataEditorReducer(state: MetadataEditorState, action: MetadataEditorAction): MetadataEditorState;

Pure reducer — exported (with initMetadataEditorState) so the edit state is testable without React, mirroring the document editor’s reducer/hook split.

Parameters

Returns

MetadataEditorState

normalizeStoragePath()

function normalizeStoragePath(path: string): string;

Strip leading/trailing slashes and collapse repeats — mirrors pyric/storage’s reference normalization so usePathState and useStorageList always agree on what a path is.

Parameters

Returns

string

ObjectBrowser()

function ObjectBrowser(__namedParameters: ObjectBrowserProps): Element;

Headless storage browser shell — renders useStorageList’s merged folder/object rows. Folder rows navigate (onNavigate with the prefix path), object rows select (onSelect with the ref). Below virtualizeThreshold renders a plain <ul>; above it, composes the package’s <VirtualList>.

Ships no visual styling. Consumers style via:

• [data-pyric-ui="object-browser"] — the root (stamps data-size)
• …[data-pyric-loading] / [data-pyric-empty] / [data-pyric-error]
• …[data-pyric-virtualized] — virtualized mode
• [data-pyric-object-browser-items] — the <ul> in plain mode
• [data-pyric-storage-entry] — each row
• [data-pyric-storage-entry][data-pyric-entry-kind="folder"|"object"]
• [data-pyric-storage-entry][data-pyric-entry-path="docs/a.txt"]
• [data-pyric-storage-entry][data-pyric-denied] — read-denied row (rules gate; reason on data-pyric-denied-reason)
• [data-pyric-entry-select] — the row button
• [data-pyric-entry-select][data-pyric-selected] — the selected object
• [data-pyric-storage-action] — optional sibling row action

Parameters

Returns

Element

ObjectInspector()

function ObjectInspector(__namedParameters: ObjectInspectorProps): Element;

Headless inspector for one storage object: metadata + a content-type-driven preview. Previews come from the registry (image/* and text/* + application/json built in; extend via previews). Blob bytes load lazily and ONLY when the matched preview asks (needsBlob) and the object is within the preview’s maxBytes cap; the blob URL is revoked on unmount/path change (see useStorageObject).

Ships no visual styling. Consumers style via:

• [data-pyric-ui="object-inspector"] — root (stamps data-size)
• …[data-pyric-idle] / [data-pyric-loading] / [data-pyric-error]
• [data-pyric-object-name] / [data-pyric-object-metadata]
• [data-pyric-metadata-field="<field>"] — each metadata row
• [data-pyric-object-preview] — the preview container, stamping data-pyric-preview="<id>" for the matched registry entry
• …[data-pyric-preview-loading] — blob in flight
• …[data-pyric-preview-error] — blob load failed
• …[data-pyric-preview-too-large] — over the preview’s cap
• …[data-pyric-preview-none] — no registry match (metadata-only)

Parameters

Returns

Element

parseCopyCounter()

function parseCopyCounter(stem: string): {
  base: string;
  counter: number;
};

Trailing (n) counter: photo (3) → base photo, counter 3. counter: null when the stem carries none. A counter beyond Number.MAX_SAFE_INTEGER is treated as plain text (no counter): incrementing it would be lossy — n + 1 === n in float land, which turns resolveCollision’s probe loop into a hang — and the candidate would render in scientific notation anyway.

Parameters

Returns

{
  base: string;
  counter: number;
}

base

base: string;

counter

counter: number;

PathBreadcrumb()

function PathBreadcrumb(__namedParameters: PathBreadcrumbProps): Element;

Headless breadcrumb for storage paths. Every crumb (including the current one) is a real <button> — clicking the current crumb is a cheap “refresh this level” affordance for consumers that wire onNavigate to a path-keyed loader.

Ships no visual styling. Consumers style via:

• [data-pyric-ui="path-breadcrumb"] — the <nav> root
• [data-pyric-breadcrumb-item] — each <li>
• [data-pyric-breadcrumb-link] — each crumb button
• [data-pyric-breadcrumb-link][data-pyric-current] — the current level
• [data-pyric-breadcrumb-root] — the root crumb’s button
• [data-pyric-breadcrumb-separator] — the separators

Parameters

Returns

Element

pendingChildFolders()

function pendingChildFolders(state: PendingPrefixState, parentPath: string): string[];

Direct-child folder NAMES pending under parentPath ('' = root), sorted. The chain expansion guarantees every level is present, so a simple parent match is exact.

Parameters

Returns

string[]

pendingPrefixReducer()

function pendingPrefixReducer(state: PendingPrefixState, action: PendingPrefixAction): PendingPrefixState;

Parameters

Returns

PendingPrefixState

planBatchNames()

function planBatchNames(relativePaths: readonly string[], taken: ReadonlySet<string>): string[];

Resolve a whole drop/pick batch against the destination folder’s existing names, with OS drop semantics: collisions are detected and renamed at the batch’s TOP LEVEL only (the names the OS drop “creates” in the destination — a plain file’s name, or a dropped folder’s root segment). Files inside a dropped folder ride their folder’s rename and keep their inner structure untouched — exactly like dropping photos/ next to an existing photos/ yields photos (1)/… with the contents intact.

Within one batch:

• all paths sharing a top-level FOLDER segment share its resolution (one dropped folder = one rename), and
• top-level FILES resolve individually in order, each claiming its resolved name, so two same-named files in one batch get successive counters.

Only the destination’s DIRECT children can be checked — that is all the drop target (one listAll level) knows. Deeper paths follow GCS overwrite semantics, which the folder-level rename already shields in practice (a colliding folder is renamed wholesale).

Returns resolved paths in input order.

Parameters

Returns

string[]

resolveCollision()

function resolveCollision(name: string, taken: ReadonlySet<string>): string;

Resolve one name against a set of taken sibling names. Returns the name unchanged when free; otherwise the first (n) candidate that is free, per the module rule above.

Parameters

Returns

string

selectStoragePreview()

function selectStoragePreview(metadata: FullMetadata, consumerPreviews: readonly StoragePreview[]): StoragePreview;

Pick the preview for metadata: consumer previews first (override channel), then the built-ins, first match wins. undefined means metadata-only.

Parameters

Returns

StoragePreview

splitStorageName()

function splitStorageName(name: string): {
  ext: string;
  stem: string;
};

name split as the rule defines: ext includes the leading dot, or is '' when the name has no extension (dotfiles, trailing dots, extensionless names).

Parameters

Returns

{
  ext: string;
  stem: string;
}

ext

ext: string;

stem

stem: string;

StorageApiProvider()

function StorageApiProvider(__namedParameters: {
  children: ReactNode;
  value: StorageApi;
}): FunctionComponentElement<ProviderProps<StorageApi>>;

Provide a Storage API bundle to the subtree (Studio’s worker client).

Parameters

Returns

FunctionComponentElement<ProviderProps<StorageApi>>

UploadDropzone()

function UploadDropzone(__namedParameters: UploadDropzoneProps): Element;

Headless drop target for file + folder uploads. Slot-based: the children render the chrome; the component owns drag wiring and stamps data-dragging while a drag hovers (a counter tracks enter/leave pairs so crossing child elements doesn’t flicker).

Ships no visual styling. Consumers style via:

• [data-pyric-ui="upload-dropzone"] — the root
• …[data-dragging] — a drag is hovering
• …[data-disabled]
• …[data-disabled-reason="…"] — why (e.g. a denied write verdict)

Parameters

Returns

Element

useMetadataEditor()

function useMetadataEditor(
   storage: FirebaseStorage,
   path: string,
   options?: UseMetadataEditorOptions): UseMetadataEditorResult;

Headless metadata editor — the useDocumentEditor reducer pattern over updateMetadata: a pure reducer owns the draft (contentType, cacheControl, customMetadata k/v rows with stable ids + empty/duplicate-key validation); the hook adds named dispatch helpers and the save half.

Parameters

Returns

UseMetadataEditorResult

useObjectUpload()

function useObjectUpload(storage: FirebaseStorage, options?: UseObjectUploadOptions): UseObjectUploadResult;

Multi-file upload over the package’s single Storage handle prop. Headless: returns task state; render it however you like (the <UploadDropzone> component is one producer of upload() calls).

Optimistic-with-rollback: with the list seam wired, each upload’s row appears in useStorageList immediately and disappears again if the write fails (typed StorageError on task.error).

Parameters

Returns

UseObjectUploadResult

usePathState()

function usePathState(options?: UsePathStateOptions): UsePathStateResult;

Path navigation state for the storage browser. Controlled when path is provided (the owner re-renders with the next value), uncontrolled otherwise — standard React value/defaultValue semantics. All emitted paths are normalized (normalizeStoragePath).

Parameters

Returns

UsePathStateResult

useStorageApi()

function useStorageApi(): StorageApi;

Read the active Storage API bundle (defaults to in-process pyric/storage).

Returns

StorageApi

useStorageDelete()

function useStorageDelete(storage: FirebaseStorage, options?: UseStorageDeleteOptions): UseStorageDeleteResult;

Drive bulk + recursive deletes from a React component — the storage counterpart of useRecursiveDelete (same progress / isRunning / error shape, same stale-run generation token), bulk because storage selections are flat multi-row affairs.

Parameters

Returns

UseStorageDeleteResult

useStorageList()

function useStorageList(storage: FirebaseStorage, path: string): UseStorageListResult;

List the objects + synthetic folders directly under path : listAll over the package’s sandbox Storage handle. Read-via-get, not realtime: the list updates on refresh, path change, or the optimistic seam. Pass '' (or the result of usePathState) for the bucket root.

listAll has no pagination; a very large prefix arrives as one flat result (virtualize the rendering, which <ObjectBrowser> does).

Parameters

Returns

UseStorageListResult

useStorageObject()

function useStorageObject(storage: FirebaseStorage, path: string): UseStorageObjectResult;

One object’s metadata + lazily-loaded bytes, the data source for <ObjectInspector>. Read-via-get like the rest of the storage half: updates on refresh, path change, or loadBlob.

Parameters

Returns

UseStorageObjectResult

useStorageRulesGate()

function useStorageRulesGate(storage: FirebaseStorage, options?: UseStorageRulesGateOptions): UseStorageRulesGateResult;

Pre-flight rules evaluation — the M7 differentiator. Evaluates the current identity against paths BEFORE the click, so components can annotate denied affordances (data-pyric-denied, disabled-with- reason) instead of letting the user discover a denial via a thrown storage/unauthorized.

Rules discovery: a sandbox handle carries its deployed ruleset (getStorageSandbox(ctx, { rules }) parses it into the handle’s StorageService) — the hook reads it through the handle’s target, so sandbox callers pass nothing. Identity likewise defaults to the handle’s SandboxContext.auth. An explicit rules or identity option overrides the handle when evaluating a what-if scenario.

Evaluation contract (mirrors pyric/storage’s own enforcement): resource (the existing object) is bound as null — the gate pre-evaluates without fetching per-path metadata, matching how the sandbox enforces listAll. Rules conditioned on existing-object state (resource.*) evaluate as if the object doesn’t exist; the common identity/path/payload-shaped rules evaluate exactly.

Parameters

Returns

UseStorageRulesGateResult

useStorageSelection()

function useStorageSelection(): UseStorageSelectionResult;

Multi-select state over storage rows, keyed by fullPath. Deliberately dumb: it doesn’t watch the list, so clear it on path change (or after a bulk op via the delete hook’s outcome) — the consumer owns that policy.

Returns

UseStorageSelectionResult