LinkedDocsPanel

Docs and links on a record

Release runbookUpdated 2 hours ago (opens in a new tab)Published
Launch briefUpdated yesterday (opens in a new tab)Draft
Design filedesign.example.com (opens in a new tab)

import { useRef, useState } from 'react';
import { LinkedDocsPanel, type LinkedDocItem } from '@rookcom/monarch-react/shell';

const START: LinkedDocItem[] = [
  {
    id: 'l1',
    kind: 'doc',
    docId: 'd1',
    title: 'Release runbook',
    href: '#doc-release-runbook',
    meta: 'Updated 2 hours ago',
    status: 'Published',
    space: { id: 's-eng', name: 'Engineering' },
  },
  {
    id: 'l2',
    kind: 'doc',
    docId: 'd2',
    title: 'Launch brief',
    href: '#doc-launch-brief',
    meta: 'Updated yesterday',
    status: 'Draft',
    space: { id: 's-mkt', name: 'Marketing' },
  },
  {
    id: 'l3',
    kind: 'link',
    title: 'Design file',
    href: 'https://design.example.com/file/123',
  },
];

const DOCS = [
  { value: 'd1', label: 'Release runbook', description: 'Engineering' },
  { value: 'd3', label: 'Incident review template', description: 'Engineering' },
  { value: 'd4', label: 'Pricing notes', description: 'Sales' },
];

function Basic() {
  const [items, setItems] = useState(START);
  const counter = useRef(10);
  const nextId = () => `l${(counter.current += 1)}`;
  return (
    <div style={{ width: '100%', maxWidth: '26rem' }}>
      <LinkedDocsPanel
        items={items}
        docOptions={DOCS}
        onLinkDoc={(docId) => {
          const doc = DOCS.find((d) => d.value === docId);
          if (doc)
            setItems((l) => [
              ...l,
              { id: nextId(), kind: 'doc', docId, title: doc.label, href: `#doc-${docId}` },
            ]);
        }}
        onCreateDoc={() => {}}
        onAddLink={({ url, title }) =>
          setItems((l) => [...l, { id: nextId(), kind: 'link', title, href: url }])
        }
        onUnlink={(it) => setItems((l) => l.filter((x) => x.id !== it.id))}
      />
    </div>
  );
}

<Basic />

Usage examples

Empty, loading and read-only

import { LinkedDocsPanel, type LinkedDocItem } from '@rookcom/monarch-react/shell';

const START: LinkedDocItem[] = [
  {
    id: 'l1',
    kind: 'doc',
    docId: 'd1',
    title: 'Release runbook',
    href: '#doc-release-runbook',
    meta: 'Updated 2 hours ago',
    status: 'Published',
    space: { id: 's-eng', name: 'Engineering' },
  },
  {
    id: 'l2',
    kind: 'doc',
    docId: 'd2',
    title: 'Launch brief',
    href: '#doc-launch-brief',
    meta: 'Updated yesterday',
    status: 'Draft',
    space: { id: 's-mkt', name: 'Marketing' },
  },
  {
    id: 'l3',
    kind: 'link',
    title: 'Design file',
    href: 'https://design.example.com/file/123',
  },
];

function States() {
  return (
    <div style={{ display: 'grid', gap: 'var(--mn-space-6)', width: '100%', maxWidth: '26rem' }}>
      <LinkedDocsPanel items={[]} onAddLink={() => {}} messages={{ title: 'Docs (empty)' }} />
      <LinkedDocsPanel items={null} messages={{ title: 'Docs (loading)' }} />
      <LinkedDocsPanel
        items={START.slice(0, 1)}
        readOnly
        messages={{ title: 'Docs (read-only)' }}
      />
    </div>
  );
}

<States />

Purpose

Records in Rook apps (tickets, tasks, campaigns, audits) link to Rook Dossier docs and to outside pages. LinkedDocsPanel is that panel on Monarch tokens, with the data and the linking left to the product.

Use when

On a record’s detail page, in a side column or a "Docs" tab.
Read-only (readOnly) for people who may see but not change links.

Avoid when

Attachments uploaded to the record itself: use FileUpload and UploadQueue.
A general list of documents: use a table or list page.

Design principles

Data in, intent out: items comes from the product; link, create, add and unlink are callbacks. The panel never fetches.
Both kinds in one list: Dossier docs (status, Space, last update) and external links (the host name shows by default).
Filter, don’t hide: Space chips appear only when items span several Spaces, and a filtered list says how many more exist.
Promise-aware: a returned promise shows progress on the row or button; a rejection becomes an alert.

API reference

import { LinkedDocsPanel, parseLinkUrl } from '@rookcom/monarch-react/shell';

Export	Kind	Rendering	Root class
`LinkedDocsPanel`	component	client	`.mn-linked-docs-panel`
`parseLinkUrl`	utility	client	–

Forwards its ref to the section. "Link doc" uses EntityPicker from @rookcom/monarch-react.

Also exported: parseLinkUrl (the add-link validator: full http(s) URLs only).

Generated from the TypeScript declarations of packages/react/src/components/collaboration/linked-docs-panel.

Properties

items={null} is loading. Each item has a row id (id); doc rows can carry docId so linked docs are left out of the picker.

"Link doc" appears with onLinkDoc and either docOptions or onSearchDocs; "New doc" with onCreateDoc; "Add link" with onAddLink.

filter: a Space id, "" for all, null for items without a Space.