d2829d6348
@crema/knowledge-ui: headless KB management components over an injected KnowledgeTransport. This commit: package + types (full API surface) + transport interface + MockKnowledgeTransport (fixtures for every surface) + _internal (cn, badges, formatters) + components-collections (CollectionList grouped by owner, CollectionCard, CollectionForm with org/read-only states) + demo + README + tsconfig.check.json. Typechecks clean. Co-Authored-By: Claude Fable 5 (build) <noreply@anthropic.com>
83 lines
3.4 KiB
Markdown
83 lines
3.4 KiB
Markdown
# @crema/knowledge-ui
|
|
|
|
Management UI for **arcadia-knowledge** — the hosted knowledge base. Ships the
|
|
collection browser, object viewer (card + provenance + supersession + citations),
|
|
claims review queue, and export flow as **pure, headless components**: shapes and
|
|
UI, never data fetching. The app injects a `KnowledgeTransport`; auth stays closed
|
|
over inside it, so components never see a token.
|
|
|
|
Built to `arcadia-knowledge-ui-spec.md`. Two consumers today: the Knowledge area
|
|
in `arcadia-personal-cloud-web` (me.sky-ai.com) and the standalone
|
|
`skyai-knowledge-web`. Same lib, different shells.
|
|
|
|
## Install (polyrepo — source alias, not npm)
|
|
|
|
Like every `@crema/*` lib, this is a path-aliased source folder. A consumer wires
|
|
it in three places:
|
|
|
|
1. **`vite.config.ts`** — resolve alias:
|
|
```ts
|
|
"@crema/knowledge-ui": libSrc("knowledge-ui") + "/index.tsx",
|
|
"@crema/knowledge-ui/": libSrc("knowledge-ui") + "/",
|
|
```
|
|
The lib also imports `@crema/file-ui` (for uploads/previews), so alias that too
|
|
if not already, and make sure `lucide-react` is in your shared-dep dedupe list.
|
|
|
|
2. **`tsconfig.json`** — paths:
|
|
```json
|
|
"@crema/knowledge-ui": ["../lib-knowledge-ui/src/index.tsx"],
|
|
"@crema/knowledge-ui/*": ["../lib-knowledge-ui/src/*"]
|
|
```
|
|
|
|
3. **`app/app.css`** — Tailwind source scan:
|
|
```css
|
|
@source "../../lib-knowledge-ui/src";
|
|
```
|
|
|
|
## Wiring the transport
|
|
|
|
The lib defines `KnowledgeTransport`; the app implements it over its KB client
|
|
(a `kb.ts` factory that closes over the session token and talks to
|
|
arcadia-knowledge `:4025` directly). See `arcadia-knowledge-ui-spec.md` §4.2.
|
|
|
|
```tsx
|
|
import { CollectionList, type KnowledgeTransport } from "@crema/knowledge-ui";
|
|
|
|
const transport: KnowledgeTransport = kbTransport(session.token);
|
|
const { collections } = await transport.listCollections();
|
|
|
|
<CollectionList collections={collections} onOpen={(c) => navigate(`/knowledge/${c.slug}`)} />
|
|
```
|
|
|
|
For development without a service, use `MockKnowledgeTransport` — it backs
|
|
`demo/knowledge.tsx` with fixtures covering every surface (personal + org
|
|
corpuses, documents, an image, a superseded doc, a vault doc, an open claim
|
|
conflict, a proposed claim, a rejected tombstone, an export job).
|
|
|
|
## Conventions
|
|
|
|
- **Tailwind theme tokens only** — no hex. Sensitivity/tier/status/curation
|
|
colours use `--warning` / `--success` / `--destructive` / `--info` (falls back
|
|
to `--primary`). Works in any Crema theme.
|
|
- **Props in, callbacks out.** No global state, no context, no fetching.
|
|
- **`data-action` attributes** on interactive elements (command-bus contract).
|
|
- **Trust is surfaced raw** — assertion tier, `card_model`, `extraction_model`
|
|
are shown as first-class facts, never collapsed into a score.
|
|
|
|
## Typecheck
|
|
|
|
```bash
|
|
../arcadia-personal-cloud-web/node_modules/.bin/tsc -p tsconfig.check.json
|
|
```
|
|
(Borrows a consumer's React types; the lib has no node_modules of its own.)
|
|
|
|
## Surfaces
|
|
|
|
| Module | Exports |
|
|
|---|---|
|
|
| `components-collections` | `CollectionList`, `CollectionCard`, `CollectionForm` |
|
|
| `components-object` | `ObjectList`, `ObjectViewer`, `CatalogCard`, `ProvenancePanel`, `SupersessionBanner`, `OutlineNav`, `TextReader`, `CitationLink` |
|
|
| `components-claims` | `ClaimsReviewQueue`, `ClaimCard`, `ConflictPair` |
|
|
| `components-export` | `ExportPanel`, `ExportJobRow` |
|
|
| `_internal` (re-exported) | badges + `cn`, `formatBytes`, `formatDate`, `formatRelative`, `renderValue` |
|