docblocks-react-ui 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,201 @@
 # docblocks-react-ui
 
+## 0.3.0
+
+### Minor Changes
+
+- 5f5ab54: The presence selection's visibility over the room stands grant-gated (the
+  privacy stand): the `EditorProvider`'s additive `presence` prop carries
+  the local user's identity (`userId` / the optional `name`) and the
+  optional `PresenceCrypto` cipher; the new `usePresenceSharing()` hook
+  drives the local grant — the session-state default is **off** (the
+  selection does not publish, only the light identity frame the roster
+  needs), and the consumer flips it to `everyone` (the plaintext wire
+  shape, the legacy stand) or to a targeted user-id list (the selection
+  publishes as opaque ciphertext entries, one per grant member — the
+  entries carry no target id, a recipient opens only the entry addressed
+  to it, an unaddressed peer sees the sharer's identity but never the
+  selection). The library orchestrates the publish gating, the receive's
+  decrypt, and the per-peer sequence guard over the async decrypt; the
+  cryptography and the sharing's UI are the consumer's stand (the package
+  ships no built-in control). A provider without the `presence` prop keeps
+  the legacy stand (the anonymous plaintext selection over the room).
+
+### Patch Changes
+
+- Updated dependencies [5971d30]
+  - docblocks-core@0.1.3
+
+## 0.2.0
+
+### Minor Changes
+
+- bcc306e: The `Editor`'s page view is now the motion row layer (the former
+  `MotionEditor`'s merge): every page block is its own `Reorder.Item` row —
+  the drag-reorder (one drag = one range move of the dragged block's
+  derived subtree), the insert/remove's layout animation, the rendered
+  list marker per row. Consumers rendering `<Editor>` get the animated,
+  draggable page without a code change; the `view` / `formatPalette` props
+  stand. The `MotionEditor` export and the `./motion` subpath are removed
+  (the base `Editor` is the motion editor — the previous split stood the
+  base entry without any reorder path, so a consumer taking it got a
+  non-reorderable editor).
+  
+  The three peers are now REQUIRED (pre-1.0 breaking): `framer-motion`
+  (the page view's row layer), `mermaid` (the `./mermaid` subpath), and
+  `pdfjs-dist` (the `./pdf` subpath) lose their `optional: true` — the
+  install must carry all of them. The `./mermaid` and `./pdf` subpaths'
+  wiring stays opt-in (the `pdfPreview` prop / the `code` block renderer);
+  the required peers guarantee availability only. The static row rendering
+  stands for the table cells and the canvas's page miniature (the
+  `BlockGroups`'s stand); the `BlockView`/`BlockNodeView` renderers are
+  unchanged.
+- d62b662: The editor's UI strings stand localized (en + ru). The language is
+  consumer-driven: the package reads the `<html lang>` attribute (the `ru*`
+  prefix stands the Russian stand; the absent or unknown language falls
+  back to English) and follows the attribute's change at runtime. There is
+  no `locale` prop.
+  
+  The package runs its own `i18next` instance over the shipped catalogs —
+  `i18next` and `react-i18next` are new runtime dependencies — under the
+  `EditorProvider`'s subtree (and the consumer-placed `DocHeader`): the
+  consumer's global `i18next` singleton stands untouched, and the editor's
+  `useTranslation` never conflicts with it. The English's values keep the
+  former's literals as-is (the zero visual diff over the English's
+  language).
+  
+  Not localized (the technical stand): the code language's names, the font
+  family's and weight's names, the avatar emoji picker's accessible names,
+  and the technical glyphs. Parameterized strings use the `{param}`
+  interpolation (the single braces' stand).
+- 0e798be: The page row's delete affordance: the hover's trash icon at the row's
+  right edge (every page type — the text rows' own wrapper, the non-text
+  rows' row-level stand over the motion view; the edit's mode only).
+  The deletion was previously discoverable only through the less obvious
+  path (the gutter's select + the Delete key). The click is a true
+  deletion (the Delete key's image special case — the in-place conversion
+  to an empty paragraph — stands for the key gesture only), the row's
+  whole blocks selection is deleted when the row is part of one (the
+  Delete key's gesture parity), and the gesture stands the document
+  root's trailing-paragraph guarantee + the focus's parking as the Delete
+  key's path (the focus never drops to the document).
+- 74e0abd: Add the standalone's database's surface (the consumer's own page, not a
+  document block): the `DatabaseTable` component (the live grid over the
+  bridge's table id — the same `useDatabaseTable`'s data stand as the
+  document block) + the `useTableList` hook (the `listTables`'s catalog
+  read + the `createTable` / `renameTable` mutations over the fresh's
+  `operationId` per op; the catalog's auto-refresh stands over the own's
+  successful mutations + the manual's `refresh`). The `DatabaseTable`'s
+  view's settings (`filter`, the `columnOrder`, the `hiddenColumns`, the
+  `columnWidths`) stand the internal's state seeded from the optional
+  `view` prop + persisted over the `onViewChange`'s patch callback (the
+  controlled's mode stands absent — one patch per change, as the block's
+  `updateBlock` stand). The `readOnly`'s stand gates the editing's paths
+  (the block's read-only's parity). The grid's `GridBody` stands extracted
+  from the document's context (the view's attrs' write is the callback's
+  stand — the block's wrapper keeps one `updateBlock` per change, no
+  behavior's diff).
+
+### Patch Changes
+
+- a89733e: The external-form database's history and boundary stands:
+  
+  - the undo / redo's in-flight window — a forward write that commits while
+    the undo's inverse (or the redo's forward) is in flight stands the
+    history's invariants: the undo's path consumes the undone op (popped from
+    the undo stack, not moved to the redo stack — the fresh write cleared the
+    redo side, and the re-commit over the newer entry would clobber it), and
+    the redo's path re-enters the op on the undo stack at the call's position
+    (below the window's writes, not on top — the undo order's inversion is
+    closed, the first undo reverts the newest write).
+  - the operation's rejections stand the structured `BridgeError` (the code's
+    retry / the clear's decision stands the first-class property, not the
+    `cause`'s dig): a rejection that carries no machine code stands the
+    transport-level `unavailable` (the safe recovery is the same-operationId's
+    reconciliation, not a blind new operation).
+  - the cell-value equality stands the element-wise comparison over the
+    composite value (the multi-select's array) — the identity stand committed
+    the no-op over the same content and pushed the undo entry.
+  - the enum's options catalog stands the full page set (the cursor's
+    continuation to the tail) over the single page's `limit: 200` — the
+    truncated catalog over 200 options stood the silent-ignored delete of the
+    truncated option over the commit's diff.
+  - the column form's commit failures stand the logged error + the catalog's
+    re-read (the partial stand over the move's second commit), the silent
+    catches are gone.
+- ff90f80: The external-form database stand's hardening: the bridge tables' picker
+  guards the `listTables` rejection (the unhandled rejection stands the
+  logged error + the empty list stand), and the hook's undo / redo drops
+  the replaced entry by identity (the in-flight inverse over the history's
+  mutation no longer drops the fresh entry — the double-apply and the
+  stale restore are closed). The database JSDoc stands the actual
+  contract: the mixed paste's description is self-contained, and the lost
+  response's reconciliation is the consumer's stand over the bridge's
+  `getOperationStatus` (the UI's convergence is the rebaseline).
+- 590f5e7: The editor root's focus-ring stand: the root is a focus park (the
+  drag's release and the gutter's delete park the focus there so the
+  keyboard's input stays scoped over the editor) and is reached
+  programmatically only (tabIndex -1) — the browser's default focus ring
+  stood the visible ring over the whole document after a drag's release.
+  The ring is suppressed (`outline: none` on the focused root); the focus
+  itself stays, and the individual controls keep their own focus styles.
+- a1564a2: The embed and frame's render stands:
+  
+  - the sync-embed's stale's dynamic stand — the ref's block removed from the
+    master over the embed's mount now stands the broken's transition (the
+    master's change re-stands the block to the render-time's check; the
+    master's undo of the removal stands the resolved's back stand).
+  - the canvas frame's window references stand memoized (the frame's drag
+    re-renders the frame on every pointermove — the fresh array / Set
+    references broke the window's copies' memo and re-rendered every copy
+    over the drag's pass; the page-frame block's window stands the same
+    stand).
+  - the pdf worker's asset stands the degradation's signal: the unreachable
+    worker's asset (the bundler's rewritten reference, the hosting's dropped
+    asset) stands the logged warning over the silent native-viewer's
+    fallback.
+  - the `docblocks-core`'s peer range stands `^0.1.0` (the required peer's
+    version stand over the `*` — the packages stand lockstep over the 0.x
+    case, the breaking core's minor stands the range's bump over the same
+    release).
+- ecb2a91: The paste's markdown link re-gate stands the mid-string control's
+  degrade: an href with a tab / LF / CR between the scheme's letters
+  (`java<tab>script:…`) no longer passes the gate — the check runs over
+  the WHATWG URL parser's full input normalization (the control is
+  removed from any position before the scheme detection, the browser's
+  parity). The run degrades to plain text over the unsafe href (the core's
+  gate is the single stand; this package's mirror passes it through).
+- d162a1a: The paste surface's hardening: the markdown paste's link stand re-checks
+  the href over the core's public `isSafeLinkHref` itself at both the raw
+  parse and the entity-decode pass (the trimmed form — the browser trims
+  the leading C0 controls before the scheme detection, so the parser's
+  mirror stands the writer's contract: the `<a href>` tag, the exposed
+  entity's scheme, and the entity-hidden leading C0 degrade the run to
+  plain text instead of aborting the multi-block paste over the core's
+  strict mark rejection); and the clipboard's HTML serializes the mark
+  values escaped (the hostile remote data's stand — the attribute break
+  over the third-party paste target is closed).
+- f907ee1: The editor store and the flat page derivation stand the registry's
+  own-property lookups (the `constructor`, `toString`, ... names are
+  unknown types, not the inherited `Object.prototype` members): a hostile
+  type named by a prototype key stands absent in the page sequence (the
+  cross-minor's stand — no renderer lookup over the inherited member, no
+  render-error stand, the data preserved in the export), and the seed and
+  the diff share one reader's posture (the store's filter and the
+  `getBlock`'s own-property stand agree on the block's presence).
+- ab836e5: The selector's escape stand: the three block-content lookups (the range
+  extend's target, the gesture's stale-restore focus, the format
+  toolbar's type-change exclude) build the `data-block-id` selector over
+  `CSS.escape` — the full parity with the package's other lookup points,
+  where a crafted block id (a quote / bracket) would otherwise stand a
+  `SyntaxError` from `querySelector` in the keyboard / gesture handlers.
+- Updated dependencies [bf92634]
+- Updated dependencies [b66e45e]
+- Updated dependencies [c5a38d2]
+- Updated dependencies [769c12a]
+- Updated dependencies [72fdfd3]
+  - docblocks-core@0.1.2
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -12,11 +12,14 @@ package renders the document and provides the editing surface
 npm i docblocks-react-ui docblocks-core
 ```
 
-Peer dependencies: `docblocks-core`, `react` (19), `react-dom`. Optional
-peers, used only by their subpaths: `framer-motion` (`./motion`), `mermaid`
-(`./mermaid`), `pdfjs-dist` (`./pdf`). The package's own runtime dependencies
-(zustand, the Radix primitives, the shared ui runtime set) are declared, so
-a plain `npm i` is the whole install.
+Peer dependencies: `docblocks-core`, `react` (19), `react-dom`, and the
+required peers `framer-motion` (the Editor's page view is the motion row
+layer — the drag-reorder + the layout animations), `mermaid` (the
+`./mermaid` subpath's renderer), and `pdfjs-dist` (the `./pdf` subpath's
+preview) — the install must carry all of them (npm enforces the required
+peers). The package's own runtime dependencies (zustand, the Radix
+primitives, the shared ui runtime set) are declared, so a plain `npm i`
+is the whole install.
 
 The package is ESM-only (`import`, not `require`); it stands Node
 `^22.22.2 || ^24.15.0 || >=26.0.0` (the `engines` field).
@@ -106,6 +109,7 @@ mention catalog). The full props list:
 | `accessLevel?`               | The consumer's user access level (default `editor`): `viewer` forces the `published` mode (the current state is never rendered to a reader).                                                                                                                                                                                           |
 | `mode?`                      | The document mode (default `edit`): `view` is a read-only live document; `published` renders the `publishedDoc` snapshot read-only.                                                                                                                                                                                                    |
 | `publishedDoc?`              | The published snapshot (a hydrated core `Doc`; must not change after mount — remount over `key` for a new snapshot). The consumer owns the publish action and the snapshot storage.                                                                                                                                                    |
+| `presence?`                  | The local user's presence identity + the selection-sharing cipher (see Presence sharing below). Without the prop the editor keeps the legacy stand (the anonymous plaintext selection, always shared over the room).                                                                                                                   |
 
 Two rules for the optional props:
 
@@ -253,6 +257,62 @@ function App() {
   `updatedAt`); staleness (dropping stale peers) is a consumer concern —
   the payload's `updatedAt` (Unix ms) is the only input.
 
+### Presence sharing
+
+The selection's visibility over the room is grant-gated (the privacy
+stand): with the `presence` prop the grant defaults to **off** — the
+selection does not publish, only the light identity frame (the roster). The
+consumer flips the grant through the hook (session state — not document
+data, not on the wire; it lives until the page reload or the provider's
+unmount):
+
+```tsx
+import { usePresenceSharing } from "docblocks-react-ui";
+
+function ShareControl() {
+  const { sharing, setSharing, peers } = usePresenceSharing();
+  // sharing: "off" | "everyone" | string[] (the local grant — the full
+  // information stands over the sharer's pane: what is shared, and to whom)
+  // setSharing(mode) — a no-op over the read-only modes; a targeted grant
+  // requires the presence prop's userId + crypto (the degraded stand
+  // stands a console warn, no crash)
+  // peers: { peerId, userId?, name?, updatedAt, selectionVisible }[] —
+  // the live roster (the identity frames are always published)
+  return <button onClick={() => setSharing(sharing === "off" ? "everyone" : "off")}>{sharing}</button>;
+}
+```
+
+The grant's modes:
+
+- **`off`** — the selection never publishes (the identity frame only).
+- **`everyone`** — the plaintext `selection` (the legacy wire shape — the
+  peers of any version render it).
+- **`[userId, …]`** (targeted) — the selection publishes as opaque
+  ciphertext entries (`selections`), one per grant member, produced by the
+  consumer's `PresenceCrypto` cipher. The entries carry **no target id**:
+  a recipient tries each entry with its own `decrypt`; an unaddressed peer
+  sees the sharer's identity in the roster but never the selection (and
+  never learns the audience).
+
+```ts
+interface PresenceCrypto {
+  /** One opaque entry per grant member (grant order; no target id inside). */
+  encrypt(selection: PresenceSelection, grant: string[]): Promise<string[]>;
+  /** Null when the entry is not addressed to the local user (or broken). */
+  decrypt(entry: string): Promise<PresenceSelection | null>;
+}
+```
+
+The library orchestrates (publish gating, the debounce, the per-peer
+sequence guard over the async decrypt, the roster) and renders the
+accepted selections through the existing overlay; the cryptography and
+the keys are the consumer's, and the sharing's UI (the toggle, the target
+picker, the indicator) is the consumer's stand over the hook — the package
+ships no built-in control. Without `crypto` the targeted mode degrades
+(the setter stands a no-op); `off` / `everyone` stand regardless. A
+provider **without** the `presence` prop keeps the legacy stand (the
+anonymous plaintext selection over the room — the 0.2.0 behavior).
+
 ### Blobs
 
 The document holds only an opaque blob key (`image.src`); the bytes live
@@ -334,6 +394,49 @@ package root: `BridgeError` (the structured error type) with
 `isDatabaseBridge`, and `useDatabaseTable(bridge, tableId, filter?)` — the
 grid controller for a consumer-owned grid over the bridge.
 
+### Standalone database table
+
+The database's UI stands outside any document as well — the
+consumer-owned "tables section" (the user's tables management, not a
+document block). The package ships the composable primitives; the
+consumer assembles its own section (the list / the UX) over
+`useTableList` and embeds the ready grid over the picked table:
+
+```tsx
+import { DatabaseTable, useTableList } from "docblocks-react-ui";
+
+function TablesSection({ bridge }: { bridge: DatabaseBridge }) {
+  const list = useTableList(bridge);
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  return (
+    <div>
+      {list.tables?.map((table) => (
+        <button key={table.id} onClick={() => setSelectedId(table.id)}>
+          {table.name}
+        </button>
+      ))}
+      {selectedId !== null && <DatabaseTable bridge={bridge} tableId={selectedId} />}
+    </div>
+  );
+}
+```
+
+- `DatabaseTable({ bridge, tableId, readOnly?, view?, onViewChange? })` —
+  the live grid over the bridge's table id (the same data stand as the
+  document block: the schema, the rows, the live events, the optimistic
+  cell layer). The view's settings (`filter`, `columnOrder`,
+  `hiddenColumns`, `columnWidths`) stand the internal state (seeded from
+  the optional `view` prop at mount); `onViewChange(patch)` receives one
+  patch per change for the consumer's persistence (the controlled mode
+  stands absent — the state is never external). `readOnly` gates the
+  editing's paths (the read-only block's parity).
+- `useTableList(bridge)` — `{ tables, loading, error, refresh, create,
+rename }`: the `listTables` catalog (the system tables stand out), the
+  `createTable` / `renameTable` mutations (the fresh `operationId` per op;
+  they reject with the `BridgeError`), and the catalog's re-read —
+  automatic over the hook's own successful mutations + manual over
+  `refresh` (the contract's catalog stands no push channel).
+
 ### Sync-embed
 
 A `sync-embed` block references another document by an opaque ref. The
@@ -382,7 +485,7 @@ const blockRenderers: BlockRendererMap = {
 
 `pdfPreview` is a component that renders a `pdf`-subtype image block's
 resolved blob as a client-side first-page preview. The `./pdf` subpath
-provides one over `pdfjs-dist` (an optional peer):
+provides one over `pdfjs-dist` (a required peer):
 
 ```tsx
 import { PdfFirstPage } from "docblocks-react-ui/pdf";
@@ -432,6 +535,25 @@ insert menu, the drag / resize / nudge / fit / draw sessions) or
 programmatically through the core's block commands. The viewport's zoom
 and pan are view state — they never reach the document.
 
+### Localization
+
+The editor's UI strings ship localized (en + ru). The language is
+consumer-driven — the package reads the `<html lang>` attribute (the `ru*`
+prefix stands the Russian stand; the absent / unknown language falls back
+to English) and follows the attribute's change at runtime (the editor
+re-renders over the flip). There is no `locale` prop — the document's
+language is the consumer's, set on `<html>`.
+
+The package runs its **own** `i18next` instance (the shipped catalogs,
+`i18next` + `react-i18next` are runtime dependencies) under the
+`EditorProvider`'s subtree — a consumer's global `i18next` singleton stands
+untouched, and the editor's `useTranslation` never leaks into (or out of)
+the consumer's setup.
+
+Not localized (the technical stand): the code language names, the font
+family / weight names, the avatar emoji picker's accessible names, and the
+technical glyphs.
+
 ### Subtree view
 
 `rootBlockId` renders the entry list of one block instead of the document
@@ -460,6 +582,8 @@ value actually changes (the store's reference-stability contract):
   local state; `null` before the mount effect ran and after unmount).
 - `usePresence()` — the remote peers' ephemeral state (the selection +
   the `updatedAt` per peer).
+- `usePresenceSharing()` — the selection-sharing grant (the session state
+  - the setter + the live roster; see Presence sharing).
 - `useMeta()` — the document meta (the reference is replaced only when
   the title changed).
 - `useEditorContext()` — the whole provider context (the store, the
@@ -474,8 +598,10 @@ value actually changes (the store's reference-stability contract):
 | `view`          | `"page"` (default) or `"canvas"` — the rendering the consumer switches   |
 | `formatPalette` | The format toolbar's color swatches (default `FORMAT_PALETTE`, exported) |
 
-`MotionEditor` (the `./motion` subpath) accepts the same props and adds the
-layout animations and drag-reorder (requires `framer-motion`).
+The page view renders the flat page sequence — every page block is its
+own row (the drag-reorder's pure framer `Reorder`, the insert/remove's
+layout animation, the rendered list marker per row) — over the required
+`framer-motion` peer.
 
 ## Subpath exports
 
@@ -484,12 +610,13 @@ layout animations and drag-reorder (requires `framer-motion`).
 | `docblocks-react-ui`            | The editor, the provider, the hooks, the primitives (the entry)                                                  |
 | `docblocks-react-ui/styles.css` | The compiled stylesheet: the utility layer + the token seed + the `--docblocks-*` mapping + the structural rules |
 | `docblocks-react-ui/theme.css`  | The pure token seed (standard tokens + the radius scale), no utility layer                                       |
-| `docblocks-react-ui/motion`     | `MotionEditor` (layout animations, insert/remove, drag-reorder; peer: `framer-motion`)                           |
 | `docblocks-react-ui/mermaid`    | The `mermaid` renderer above `code { language: "mermaid" }` blocks (peer: `mermaid`)                             |
 | `docblocks-react-ui/pdf`        | `PdfFirstPage` (the first-page preview over `pdfjs-dist`; the worker is copied to `dist/pdf/` at build time)     |
 
-The base entry imports none of the optional peers, so consumers who skip a
-subpath ship no extra weight.
+The `./mermaid` and `./pdf` subpaths' wiring is opt-in (the `pdfPreview`
+prop / the `code` block renderer): a consumer who skips a subpath imports
+nothing of its module. The peers themselves are required installs (the
+page view's framer import included).
 
 ## Theming