npm - @pyric/cli - Versions diffs - 0.1.0-alpha.9 - Mend

@pyric/cli 0.1.0-alpha.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1169) hide show

package/dist/serve/docs-ui/docs/ui-firestore-documentlist.md ADDED Viewed

@@ -0,0 +1,92 @@
+# `<DocumentList>`
+Headless list renderer for documents in a collection. Above `virtualizeThreshold` (default 100), switches to virtualized rendering via `<VirtualList>`; below, renders a plain `<ul>`.
+```ts
+import { DocumentList } from '@pyric/ui/firestore';
+```
+## Example
+```tsx
+import { useDocumentList } from '@pyric/ui/firestore/hooks';
+function DocsPane({ collection }) {
+  const {
+    documents,
+    hasMore,
+    loadMore,
+    isLoading,
+    error,
+  } = useDocumentList({ collection, pageSize: 50 });
+  return (
+    <DocumentList
+      documents={documents}
+      isLoading={isLoading}
+      error={error}
+      hasMore={hasMore}
+      onLoadMore={loadMore}
+      onSelect={(ref) => navigate(ref.path)}
+      renderLabel={(doc) => (
+        <span className="flex justify-between">
+          <span>{doc.id}</span>
+          <span className="text-gray-500">
+            {Object.keys(doc.data() ?? {}).length} fields
+          </span>
+        </span>
+      )}
+    />
+  );
+}
+```
+## Props
+| Prop | Type | Description |
+|---|---|---|
+| `documents` | `QueryDocumentSnapshot[]` | The list to render. |
+| `isLoading` | `boolean` | Renders the loading state when no documents yet. |
+| `error` | `Error` | Renders an `role="alert"` container. |
+| `hasMore` | `boolean` | If true AND `onLoadMore` is provided, renders a Load More button. |
+| `onSelect` | `(ref: DocumentReference) => void` | Fired on row click. |
+| `onLoadMore` | `() => void` | Wire to `useDocumentList.loadMore`. Button is hidden if not provided. |
+| `renderLabel` | `(doc: QueryDocumentSnapshot) => ReactNode` | Optional row-label override. Default renders `doc.id`. |
+| `emptyState` | `ReactNode` | Rendered when no documents. |
+| `className` | `string` | Forwarded to the root. |
+| `virtualizeThreshold` | `number` | Default `100`. Set to `Infinity` to disable virtualization. |
+| `rowHeight` | `number \| (i: number) => number` | Default `36`. TanStack measures real heights after first paint regardless. |
+| `virtualizedHeight` | `number \| string` | Scroll-container height when virtualized. Default `'60vh'`. |
+## Pagination
+`useDocumentList` exposes cursor-based pagination via `startAfter()` under the hood. The consumer never sees cursors — just `documents` (accumulating across pages), `hasMore`, and `loadMore()`.
+This is **read-via-get, not realtime.** For realtime, use `useFirestoreCollection(query)` directly. Combining pagination + realtime is non-trivial; deferred until a real use case demands it.
+## Styling hooks
+```
+[data-pyric-ui="document-list"]
+[data-pyric-ui="document-list"][data-pyric-loading]
+[data-pyric-ui="document-list"][data-pyric-empty]
+[data-pyric-ui="document-list"][data-pyric-error]
+[data-pyric-ui="document-list"][data-pyric-virtualized]
+[data-pyric-document-list-items]      /* the <ul> in non-virtualized mode */
+[data-pyric-document-entry]
+[data-pyric-document-entry][data-pyric-document-id="alice"]
+[data-pyric-document-select]
+[data-pyric-load-more]
+```
+## Notes
+- **Infinite scroll** isn't built in. Wire your own `IntersectionObserver` against the last rendered row's element and call `onLoadMore` when it intersects.
+- **`renderLabel` runs per row** — keep it cheap (no async work). React.memo around your custom label is fine if you need it.
+- **Snapshot `.ref` access** uses a structural cast under the hood — both backend shapes carry it at runtime but `pyric/firestore`'s modular interface omits it. Safe for both sandbox and prod refs.
+## See also
+- [`<CollectionList>`](../ui-firestore-collectionlist/) — the collections-under-parent counterpart.
+- [`<VirtualList>`](../ui-primitives-virtuallist/) — the underlying virtualizer.
+- `useDocumentList`, `useFirestoreCollection` — data sources.

package/dist/serve/docs-ui/docs/ui-firestore-documentpreview/index.html ADDED Viewed

@@ -0,0 +1,159 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>&lt;DocumentPreview&gt; · Pyric Studio</title><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link rel="stylesheet" href="/__pyric/ui/_astro/_slug_.CQYSemvw.css"></head> <body>  <header class="studio__bar"> <div class="studio__bar-inner"> <a class="studio__brand" href="/__pyric/ui/" aria-label="Pyric Studio">Pyric</a> <nav class="studio__nav" aria-label="Studio tabs"> <a class="studio__nav-tab" href="/__pyric/ui/"> Home </a><a class="studio__nav-tab" href="/__pyric/ui/firestore"> Firestore </a><a class="studio__nav-tab" href="/__pyric/ui/auth"> Auth </a><a class="studio__nav-tab" href="/__pyric/ui/rtdb"> RTDB </a><a class="studio__nav-tab" href="/__pyric/ui/storage"> Storage </a><a class="studio__nav-tab" href="/__pyric/ui/traffic"> Traffic </a><a class="studio__nav-tab" href="/__pyric/ui/settings"> Settings </a><a class="studio__nav-tab" href="/__pyric/ui/docs" aria-current="page"> Docs </a> </nav> </div> </header> <div class="docs-shell">  <details class="docs-nav-drawer"> <summary>Navigate</summary> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div> <script type="module">let i=null;function d(t){return i||(i=fetch(t).then(e=>e.json())),i}function l(t,e){return t.title.toLowerCase().includes(e)||t.excerpt.toLowerCase().includes(e)?!0:t.headings.some(r=>r.text.toLowerCase().includes(e))}function u(t,e,r){if(e.innerHTML="",t.length===0){e.hidden=!1;{const n=document.createElement("li");n.className="docs-search-empty",n.textContent="No matches",e.appendChild(n)}return}e.hidden=!1;for(const n of t.slice(0,8)){const s=document.createElement("li"),c=document.createElement("a");c.href=n.path;const o=document.createElement("span");o.className="docs-search-result-title",o.textContent=n.title;const a=document.createElement("span");a.className="docs-search-result-meta",a.textContent=[n.group,n.section].filter(Boolean).join(" / "),c.append(o,a),s.appendChild(c),e.appendChild(s)}}document.querySelectorAll(".docs-search").forEach(t=>{const e=t.dataset.indexUrl,r=t.querySelector(".docs-search-input"),n=t.querySelector(".docs-search-results");r.addEventListener("input",async()=>{const s=r.value.trim().toLowerCase();if(!s){n.hidden=!0,n.innerHTML="";return}const{pages:c}=await d(e);r.value.trim().toLowerCase()===s&&u(c.filter(o=>l(o,s)),n)}),r.addEventListener("focus",()=>{d(e),n.childElementCount>0&&(n.hidden=!1)}),r.addEventListener("keydown",s=>{s.key==="Escape"&&(r.value="",n.hidden=!0,n.innerHTML="",r.blur())}),r.addEventListener("blur",()=>{window.setTimeout(()=>{n.hidden=!0},150)})});document.addEventListener("keydown",t=>{if(!(t.metaKey||t.ctrlKey)||t.key.toLowerCase()!=="k")return;const e=[...document.querySelectorAll(".docs-search-input")].find(r=>r.offsetParent!==null);e&&(t.preventDefault(),e.focus(),e.select())});</script> <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/"> Overview </a><details class="docs-nav-group"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/" aria-current="true"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> </details> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div>  <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/" id="nav-group-overview"> Overview </a><details class="docs-nav-group" id="nav-group-run-locally"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-develop-with-firebase-apis"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-inspect-and-correct"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-inspect-the-sandbox"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-correct-security-rules"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-work-with-an-agent"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-verify-the-boundary"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-unchanged"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-conformance"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" id="nav-group-reference" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/" aria-current="true"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> <main class="doc-main"> <nav class="docs-breadcrumbs" aria-label="Breadcrumb"> <ol> <li>  <a href="/__pyric/ui/docs/ui/">@pyric/ui</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Firestore</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">&lt;DocumentPreview&gt;</span> </li> </ol> </nav>  <article class="prose">  <h1 id="documentpreview"><code>&#x3C;DocumentPreview></code></h1>
+<p>Read-only renderer for a Firestore document. Iterates top-level fields in lexicographic order; dispatches each value through the field-editor registry on its inferred type.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">DocumentPreview</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/ui/firestore'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<h2 id="example">Example</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="tsx"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">useFirestoreDoc</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/ui/firestore'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">function</span><span style="color:#61AFEF"> UserPreview</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75;font-style:italic">ref</span><span style="color:#ABB2BF"> }) {</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#ABB2BF"> { </span><span style="color:#E5C07B">data</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">isLoading</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">error</span><span style="color:#ABB2BF"> } </span><span style="color:#56B6C2">=</span><span style="color:#61AFEF"> useFirestoreDoc</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">ref</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">  if</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75">error</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">return</span><span style="color:#ABB2BF"> &#x3C;</span><span style="color:#E5C07B">ErrorRow</span><span style="color:#D19A66;font-style:italic"> message</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#E5C07B">error</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">message</span><span style="color:#C678DD">}</span><span style="color:#ABB2BF"> />;</span></span>
+<span class="line"><span style="color:#C678DD">  if</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75">isLoading</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">return</span><span style="color:#ABB2BF"> &#x3C;</span><span style="color:#E5C07B">Spinner</span><span style="color:#ABB2BF"> />;</span></span>
+<span class="line"><span style="color:#C678DD">  return</span><span style="color:#ABB2BF"> (</span></span>
+<span class="line"><span style="color:#ABB2BF">    &#x3C;</span><span style="color:#E5C07B">DocumentPreview</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">      snapshot</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#E06C75">data</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">      onReferenceClick</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">targetRef</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#61AFEF"> navigate</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">targetRef</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">path</span><span style="color:#ABB2BF">)</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">      emptyState</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E06C75">p</span><span style="color:#ABB2BF">>No such document.&#x3C;/</span><span style="color:#E06C75">p</span><span style="color:#ABB2BF">></span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#ABB2BF">    /></span></span>
+<span class="line"><span style="color:#ABB2BF">  );</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<h2 id="props">Props</h2>
+<div class="table-scroll">
+<table><thead><tr><th>Prop</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><code>snapshot</code></td><td><code>DocumentSnapshot | null | undefined</code></td><td>yes</td><td>Snapshot from <code>useFirestoreDoc</code> or <code>getDoc</code>. Null/undefined or non-existent renders the empty state.</td></tr><tr><td><code>fieldEditors</code></td><td><code>FieldEditorRegistry</code></td><td>no</td><td>Override or extend the built-in editors. Merged into the defaults — only the keys you provide override.</td></tr><tr><td><code>emptyState</code></td><td><code>ReactNode</code></td><td>no</td><td>Rendered when snapshot is null or <code>!exists()</code>. Default <code>null</code>.</td></tr><tr><td><code>className</code></td><td><code>string</code></td><td>no</td><td>Forwarded to the root <code>&#x3C;div></code>.</td></tr><tr><td><code>onReferenceClick</code></td><td><code>(ref: DocumentReference) => void</code></td><td>no</td><td>When provided, reference fields render as clickable <code>&#x3C;button></code> with <code>data-pyric-clickable</code>. Without it, references stay inert <code>&#x3C;span></code>s.</td></tr></tbody></table></div>
+<h2 id="field-type-rendering">Field-type rendering</h2>
+<p>Each field type renders to a different element with a <code>data-pyric-field-type</code> attribute:</p>
+<div class="table-scroll">
+<table><thead><tr><th>Type</th><th>Element</th><th>Attributes</th><th>Notes</th></tr></thead><tbody><tr><td><code>string</code></td><td><code>&#x3C;span></code></td><td><code>data-pyric-field-type="string"</code></td><td></td></tr><tr><td><code>number</code></td><td><code>&#x3C;span></code></td><td><code>data-pyric-field-type="number"</code></td><td><code>String(value)</code></td></tr><tr><td><code>boolean</code></td><td><code>&#x3C;span></code></td><td><code>data-pyric-field-type="boolean" data-value="true"</code></td><td></td></tr><tr><td><code>null</code></td><td><code>&#x3C;span></code></td><td><code>data-pyric-field-type="null"</code></td><td>Renders <code>"null"</code> text</td></tr><tr><td><code>timestamp</code></td><td><code>&#x3C;time></code></td><td><code>dateTime={iso}</code></td><td>ISO 8601</td></tr><tr><td><code>geopoint</code></td><td><code>&#x3C;span></code></td><td><code>data-lat data-lng</code></td><td><code>"lat, lng"</code> text</td></tr><tr><td><code>reference</code></td><td><code>&#x3C;span></code> or <code>&#x3C;button></code></td><td><code>data-target-path</code> + <code>data-pyric-clickable</code> when onClick wired</td><td></td></tr><tr><td><code>bytes</code></td><td><code>&#x3C;code></code></td><td><code>data-byte-length</code></td><td>base64</td></tr><tr><td><code>map</code></td><td><code>&#x3C;dl></code></td><td>—</td><td>Recursive, lex-sorted keys</td></tr><tr><td><code>array</code></td><td><code>&#x3C;ol></code></td><td>—</td><td>Recursive, insertion order</td></tr></tbody></table></div>
+<h2 id="container-queries">Container queries</h2>
+<p>The root emits <code>data-size="narrow" \| "medium" \| "wide"</code> (breakpoints: 480 / 768 px) measured against its container via <code>ResizeObserver</code>. Style responsively with attribute selectors instead of viewport media queries.</p>
+<h2 id="customizing-per-type-rendering">Customizing per-type rendering</h2>
+<p>Pass a partial <code>fieldEditors</code> registry to override one type. The override merges into the defaults, so unspecified types keep the built-in renderer.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="tsx"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  defaultFieldEditors</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#C678DD">  type</span><span style="color:#E06C75"> FieldEditorContract</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">} </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/ui/firestore'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> customString</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">FieldEditorContract</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">> </span><span style="color:#56B6C2">=</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  type</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'string'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#61AFEF">  Display</span><span style="color:#ABB2BF">: ({ </span><span style="color:#E06C75;font-style:italic">value</span><span style="color:#ABB2BF"> }) </span><span style="color:#C678DD">=></span><span style="color:#ABB2BF"> &#x3C;</span><span style="color:#E06C75">em</span><span style="color:#ABB2BF">></span><span style="color:#C678DD">{</span><span style="color:#E5C07B">value</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">toUpperCase</span><span style="color:#ABB2BF">()</span><span style="color:#C678DD">}</span><span style="color:#ABB2BF">&#x3C;/</span><span style="color:#E06C75">em</span><span style="color:#ABB2BF">>,</span></span>
+<span class="line"><span style="color:#ABB2BF">};</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">DocumentPreview</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">  snapshot</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#E06C75">snap</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">  fieldEditors</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#ABB2BF">{ </span><span style="color:#E06C75">string</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">customString</span><span style="color:#ABB2BF"> }</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#ABB2BF">/></span></span></code></pre>
+<h2 id="see-also">See also</h2>
+<ul>
+<li><a href="../ui-firestore-documenteditor/"><code>&#x3C;DocumentEditor></code></a> — the editable counterpart.</li>
+<li><code>useFirestoreDoc(ref)</code> — fetches the snapshot via <code>onSnapshot</code>.</li>
+<li><code>inferType(value)</code> — the type discriminator used internally.</li>
+</ul>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#example">Example</a> </li><li data-depth="2"> <a href="#props">Props</a> </li><li data-depth="2"> <a href="#field-type-rendering">Field-type rendering</a> </li><li data-depth="2"> <a href="#container-queries">Container queries</a> </li><li data-depth="2"> <a href="#customizing-per-type-rendering">Customizing per-type rendering</a> </li><li data-depth="2"> <a href="#see-also">See also</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script> </body> </html>

package/dist/serve/docs-ui/docs/ui-firestore-documentpreview.md ADDED Viewed

@@ -0,0 +1,84 @@
+# `<DocumentPreview>`
+Read-only renderer for a Firestore document. Iterates top-level fields in lexicographic order; dispatches each value through the field-editor registry on its inferred type.
+```ts
+import { DocumentPreview } from '@pyric/ui/firestore';
+```
+## Example
+```tsx
+import { useFirestoreDoc } from '@pyric/ui/firestore';
+function UserPreview({ ref }) {
+  const { data, isLoading, error } = useFirestoreDoc(ref);
+  if (error) return <ErrorRow message={error.message} />;
+  if (isLoading) return <Spinner />;
+  return (
+    <DocumentPreview
+      snapshot={data}
+      onReferenceClick={(targetRef) => navigate(targetRef.path)}
+      emptyState={<p>No such document.</p>}
+    />
+  );
+}
+```
+## Props
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `snapshot` | `DocumentSnapshot \| null \| undefined` | yes | Snapshot from `useFirestoreDoc` or `getDoc`. Null/undefined or non-existent renders the empty state. |
+| `fieldEditors` | `FieldEditorRegistry` | no | Override or extend the built-in editors. Merged into the defaults — only the keys you provide override. |
+| `emptyState` | `ReactNode` | no | Rendered when snapshot is null or `!exists()`. Default `null`. |
+| `className` | `string` | no | Forwarded to the root `<div>`. |
+| `onReferenceClick` | `(ref: DocumentReference) => void` | no | When provided, reference fields render as clickable `<button>` with `data-pyric-clickable`. Without it, references stay inert `<span>`s. |
+## Field-type rendering
+Each field type renders to a different element with a `data-pyric-field-type` attribute:
+| Type | Element | Attributes | Notes |
+|---|---|---|---|
+| `string` | `<span>` | `data-pyric-field-type="string"` | |
+| `number` | `<span>` | `data-pyric-field-type="number"` | `String(value)` |
+| `boolean` | `<span>` | `data-pyric-field-type="boolean" data-value="true"` | |
+| `null` | `<span>` | `data-pyric-field-type="null"` | Renders `"null"` text |
+| `timestamp` | `<time>` | `dateTime={iso}` | ISO 8601 |
+| `geopoint` | `<span>` | `data-lat data-lng` | `"lat, lng"` text |
+| `reference` | `<span>` or `<button>` | `data-target-path` + `data-pyric-clickable` when onClick wired | |
+| `bytes` | `<code>` | `data-byte-length` | base64 |
+| `map` | `<dl>` | — | Recursive, lex-sorted keys |
+| `array` | `<ol>` | — | Recursive, insertion order |
+## Container queries
+The root emits `data-size="narrow" \| "medium" \| "wide"` (breakpoints: 480 / 768 px) measured against its container via `ResizeObserver`. Style responsively with attribute selectors instead of viewport media queries.
+## Customizing per-type rendering
+Pass a partial `fieldEditors` registry to override one type. The override merges into the defaults, so unspecified types keep the built-in renderer.
+```tsx
+import {
+  defaultFieldEditors,
+  type FieldEditorContract,
+} from '@pyric/ui/firestore';
+const customString: FieldEditorContract<string> = {
+  type: 'string',
+  Display: ({ value }) => <em>{value.toUpperCase()}</em>,
+};
+<DocumentPreview
+  snapshot={snap}
+  fieldEditors={{ string: customString }}
+/>
+```
+## See also
+- [`<DocumentEditor>`](../ui-firestore-documenteditor/) — the editable counterpart.
+- `useFirestoreDoc(ref)` — fetches the snapshot via `onSnapshot`.
+- `inferType(value)` — the type discriminator used internally.