@arbidocs/blocks 0.4.4 → 0.4.6

package/README.md

@@ -65,6 +65,8 @@ Every capability is its own entry, so a bundler only loads what you use:
 | `@arbidocs/blocks` | Light root: theme, primitives, chat, shell, auth, retrieval, agents, citations, collaboration, site blocks | none (zustand, dompurify) |
 | `/chat`, `/shell`, `/auth`, `/retrieval`, `/citations`, `/collaboration`, `/agents`, `/timeline`, `/site` | one capability each | none |
 | `/files`, `/facts` | document grid, facts table | `ag-grid-*` |
+| `/artifacts` | artifact editor, version bar, track changes | none |
+| `/artifacts/editor` | rich-text (markdown) editing surface | `@mdxeditor/editor` (optional peer) |
 | `/home`, `/workspaces` | dashboard, workspace cards and forms | `@dnd-kit/*` |
 | `/settings` | settings, billing, modals | `cmdk` |
 | `/connect` | demo/live connection layer | `@tanstack/react-query` |
@@ -94,24 +96,57 @@ import { PassagePill } from '@arbidocs/blocks/citations'
 
 ## Assistant chat page
 
-`ChatPage` (`@arbidocs/blocks/chat`) is a whole assistant chat: conversations with auto-titles, markdown
-answers, composer with a document chip and upload, empty, error and retry states, plus `header` and `aside`
-(workflow launcher) slots. It sizes to its container, so it holds up beside an open dock. Bind it with the
-`@arbidocs/react` hook:
+`ChatPage` (`@arbidocs/blocks/chat`) is a whole assistant chat: the workspace's stored conversations (backend
+titles, history loads on open), markdown answers whose citations are quiet numbered marks with a source popover
+(document, page, passage, an open action through `onOpenCitation`), composer with a document chip, upload and a stop
+button, empty, error and retry states, plus `header` and `aside` (workflow launcher) slots. It lays itself out by
+its own width (`asideBreakpoint`, default 60rem: column above, one floating panel below) and has `fillHeight` /
+`compactHeader` for a chat card under a page header. Bind it with the `@arbidocs/react` hook:
 
 ```tsx
 import { ChatPage, useChatSurface } from '@arbidocs/blocks/chat'
 import { useConnectedChat } from '@arbidocs/blocks/connect' // or useArbiChat({ workspaceId }) from @arbidocs/react
 
 const chat = useConnectedChat()
-<ChatPage chat={chat} header={<h2>Assistant</h2>} aside={<WorkflowLauncher … />} />
+<ChatPage
+  chat={chat}
+  fillHeight compactHeader
+  onOpenCitation={(t) => openDocument(t.documentId, t.page)}
+  aside={<WorkflowLauncher … />}
+/>
 
 // The dock yields to a mounted page chat:
 const { isDockAvailable } = useChatSurface()
 {isDockAvailable && <MyDock />}
 ```
 
-Theme the user bubble with `--chat-user-bubble` and `--chat-user-bubble-foreground` (HSL triplets).
+Theme the user bubble with `--chat-user-bubble` and `--chat-user-bubble-foreground` (HSL triplets). The
+live example (`examples/react-chat`, sign in, pick a workspace, chat) and the mock-data
+`packages/arbi-blocks/examples/custom-ui` (`npm run example:dev`) both mount it.
+
+## Edit an artifact, save versions, compare
+
+`/artifacts` is the surface for an AI-drafted document the user may edit: a toolbar (Edit, Cancel,
+Compare, Save as a new version), a version bar ("Version 2 of 3", a list, Compare with previous),
+and Word-style track changes between two versions with a per-change undo. It is presentational:
+state comes from `useArtifactSession` in `@arbidocs/react/artifacts`, and the editor and redline are
+slots.
+
+```tsx
+import { ArtifactEditor, ArtifactRedlineView } from '@arbidocs/blocks/artifacts'
+import { ArtifactMarkdownEditor } from '@arbidocs/blocks/artifacts/editor'
+import { renderArtifactMarkdown, useArtifactSession } from '@arbidocs/react/artifacts'
+import '@mdxeditor/editor/style.css'
+
+const s = useArtifactSession({ workspaceId, docId, onSaved: ({ docId: next }) => next && open(next) })
+<ArtifactEditor {...s.view} onOpenVersion={open} renderMarkdown={renderArtifactMarkdown}
+  editor={<ArtifactMarkdownEditor {...s.editorProps} />}
+  redline={<ArtifactRedlineView {...s.redlineProps} renderMarkdown={renderArtifactMarkdown} />} />
+```
+
+Every part takes `labels` and `testIds`; Mod+S saves while editing; touch targets are 44px. The
+editor needs `@mdxeditor/editor` (optional peer) and is heavy (mount it behind `lazy`) and needs the global `Prism` defined before it loads (`@lexical/code` reads it while it evaluates): in the module that lazily imports the editor, import first a side-effect module with `import Prism from 'prismjs'; globalThis.Prism = Prism`. A library cannot order that reliably across bundlers.
+See `examples/custom-ui/ArtifactPage.tsx` for a custom editing surface on in-memory data.
 
 ## Editorial site parts
 
@@ -135,6 +170,36 @@ import { EditorialHero, EditorialSection, PanelGrid, CtaBand } from '@arbidocs/b
 See `examples/custom-ui/MarketingPage.tsx` for a full page and `docs/design/blocks-package.md` for
 the part table.
 
+## Phone shell: tab bar, install prompt, bottom inset
+
+```tsx
+import { InstallPrompt, MobileTabBar, Shell } from '@arbidocs/blocks/shell'
+
+const items: NavItem[] = [
+  { id: 'chat', label: 'AI Assistant', shortLabel: 'Assistant', icon: <Chat />, onSelect },
+  // ...
+]
+<Shell.Root tabBar={<MobileTabBar items={items} />} overlays={<InstallPrompt appName="Clarum" />}>
+```
+
+- `MobileTabBar` labels wrap at word boundaries and are never ellipsised. Give an item a `shortLabel`
+  and a tab narrower than 5.5rem shows it (the full label stays the accessible name).
+- `InstallPrompt` is a floating "Install app" pill: shown only when the browser fired
+  `beforeinstallprompt` (or on iOS, where it expands the Add to Home Screen steps), not when already
+  installed, dismissible with the dismissal remembered (`dismissDays`, default 30). Both targets are
+  44px on a phone. `useInstallPrompt()` / `initInstallPrompt()` / `getInstallInstructions()` are the
+  headless parts (call `initInstallPrompt()` at app start so the one-shot event is not missed).
+  `autoPromptParam="install"` makes `/?install=true` open the native dialog.
+- `--shell-bottom-inset` (on `<html>`) is how far the bottom bars reach up from the screen edge:
+  `MobileTabBar` and `Composer.Root` publish it (`useShellBottomInset(ref)` for your own bar). The
+  install prompt, and anything else floating at the bottom, positions itself with
+  `calc(var(--shell-bottom-inset, 0px) + 0.75rem)` so it never covers a tab label or the composer.
+- Scroll containers use the `scrollbar-themed` utility class from `blocks.css` (thin, token-coloured;
+  override with `--scrollbar-thumb` / `--scrollbar-track`). Sidebar, dialogs and the chat list have it.
+- Browser check: `npm run example:dev` (add `-- --port 5331`), or `npm run example:build` then
+  `npm run example:preview`; `npm run example:test:e2e` measures the example at 360 and 390px
+  against the production build.
+
 ## Workspaces: gallery and switcher in a few lines
 
 ```tsx