@estiva-app/ui 0.108.2 → 0.110.0

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/ui",
3
- "version": "0.108.2",
3
+ "version": "0.110.0",
4
4
  "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/registry.json CHANGED
@@ -4,9 +4,9 @@
4
4
  "kind": "package",
5
5
  "repo": "estiva-ui",
6
6
  "package": "@estiva-app/ui",
7
- "packageVersion": "0.108.2",
8
- "exports": 250,
9
- "typeExports": 259,
7
+ "packageVersion": "0.110.0",
8
+ "exports": 251,
9
+ "typeExports": 260,
10
10
  "files": null
11
11
  },
12
12
  "storybook": {
@@ -2765,6 +2765,12 @@
2765
2765
  "purpose": "One comment, the same in every app: who, when, the words, files, cards, reactions and the way into its replies, with the actions on hover and the ⋯ menu.",
2766
2766
  "purposeFrom": "page",
2767
2767
  "props": [
2768
+ {
2769
+ "name": "heading",
2770
+ "takes": "anything",
2771
+ "required": false,
2772
+ "note": "Where it was said, at the top of the card: a `ConversationHeading`, when one list mixes conversations from several places."
2773
+ },
2768
2774
  {
2769
2775
  "name": "deleted",
2770
2776
  "takes": "true/false",
@@ -3010,6 +3016,59 @@
3010
3016
  "app": null,
3011
3017
  "looks": []
3012
3018
  },
3019
+ {
3020
+ "name": "ConversationHeading",
3021
+ "repo": "estiva-ui",
3022
+ "kind": "component",
3023
+ "importPath": "@estiva-app/ui",
3024
+ "sourceFile": "src/ConversationHeading.tsx",
3025
+ "purpose": "Which place a conversation is on, inside its card, when one list mixes conversations from several places.",
3026
+ "purposeFrom": "page",
3027
+ "props": [
3028
+ {
3029
+ "name": "icon",
3030
+ "takes": "anything",
3031
+ "required": true,
3032
+ "note": "What kind of place it is: a `KindIcon`, 16px."
3033
+ },
3034
+ {
3035
+ "name": "name",
3036
+ "takes": "text",
3037
+ "required": true,
3038
+ "note": "The place's name, cut to the column."
3039
+ },
3040
+ {
3041
+ "name": "onOpen",
3042
+ "takes": "a handler",
3043
+ "required": false,
3044
+ "note": "Pressing the name opens the place. Without it (and without `href`) the name is plain text."
3045
+ },
3046
+ {
3047
+ "name": "href",
3048
+ "takes": "text",
3049
+ "required": false,
3050
+ "note": "Or a link to the place. With `onOpen` too, a plain click calls `onOpen` and the link only serves a new tab."
3051
+ },
3052
+ {
3053
+ "name": "className",
3054
+ "takes": "text",
3055
+ "required": false,
3056
+ "note": "Placement only."
3057
+ }
3058
+ ],
3059
+ "variants": [],
3060
+ "ownsBehaviours": [],
3061
+ "status": "stable",
3062
+ "migrationStage": null,
3063
+ "docsId": "conversation-conversationheading--docs",
3064
+ "storyId": "conversation-conversationheading--on-a-card",
3065
+ "docPage": "src/ConversationHeading.mdx",
3066
+ "app": null,
3067
+ "looks": [
3068
+ "-mx-1 truncate rounded text-left text-h4 text-text-primary",
3069
+ "-mx-1 truncate rounded text-left text-h4 text-text-primary hover:bg-bg-hover"
3070
+ ]
3071
+ },
3013
3072
  {
3014
3073
  "name": "ConversationLayout",
3015
3074
  "repo": "estiva-ui",
@@ -8857,6 +8916,18 @@
8857
8916
  "takes": "text",
8858
8917
  "required": false,
8859
8918
  "note": "A part with no words, a picture or a whole block: what it is, in the app's words (\"Picture: plan.png\")."
8919
+ },
8920
+ {
8921
+ "name": "href",
8922
+ "takes": "text",
8923
+ "required": false,
8924
+ "note": "Where the words are in their file, when the reader is not looking at it: the words open it there."
8925
+ },
8926
+ {
8927
+ "name": "external",
8928
+ "takes": "true/false",
8929
+ "required": false,
8930
+ "note": "`href` is another app's: it opens in a new tab."
8860
8931
  }
8861
8932
  ],
8862
8933
  "variants": [
@@ -95,6 +95,11 @@ export interface ConversationEntryProps {
95
95
  }
96
96
 
97
97
  export interface ConversationCardProps extends ConversationEntryProps {
98
+ /**
99
+ * Where it was said, at the top of the card: a `ConversationHeading`, when one list mixes conversations from several
100
+ * places. Drawn on a deleted one too: its replies still belong there.
101
+ */
102
+ heading?: ReactNode
98
103
  /** Deleted: "This comment was deleted.", and its replies stay. */
99
104
  deleted?: boolean
100
105
  /**
@@ -182,7 +187,10 @@ function useClearOfStrip(root: RefObject<HTMLDivElement | null>, strip: RefObjec
182
187
  return
183
188
  }
184
189
  const stop = strip.current.getBoundingClientRect().left - 8
185
- const reach = Math.max(...Array.from(words.children, (part) => part.getBoundingClientRect().right))
190
+ // A heading above the face is the top row the strip stands over: its name fades at the same point.
191
+ const heading = root.current?.querySelector<HTMLElement>('[data-conversation-heading]')
192
+ const parts = [...Array.from(words.children), ...(heading ? Array.from(heading.children) : [])]
193
+ const reach = Math.max(...parts.map((part) => part.getBoundingClientRect().right))
186
194
  setEnd(reach > stop ? stop - words.getBoundingClientRect().left : undefined)
187
195
  }, [root, strip, shown])
188
196
  return end
@@ -300,9 +308,11 @@ function Reactions({ reactions, refused, readOnly }: { reactions?: ReactionRowPr
300
308
  }
301
309
 
302
310
  /** Being edited: the face beside the app's box, which holds the words, the files and the cards. */
303
- function Editing({ author, children }: { author: ConversationPerson; children: ReactNode }) {
311
+ function Editing({ author, heading, children }: { author: ConversationPerson; heading?: ReactNode; children: ReactNode }) {
304
312
  return (
305
313
  <div className="p-2">
314
+ {/* Where it was said stays while it is edited: the card keeps its height and its place. */}
315
+ {!!heading && <div className="w-full pb-2">{heading}</div>}
306
316
  <div className="flex items-start gap-2">
307
317
  <Avatar size={24} src={author.picture} alt={author.name} bot={author.bot} className="mt-1 shrink-0" />
308
318
  <div className="min-w-0 flex-1">{children}</div>
@@ -383,7 +393,7 @@ function useEditing(editing: boolean | undefined, onEditingChange: ((editing: bo
383
393
  * The same card in every app, each in its own colours (the record that makes one conversation). Peek's, moved.
384
394
  */
385
395
  export function ConversationCard(props: ConversationCardProps) {
386
- const { author, about, files, reactions, isNew = false, urgent = false, own = false, editor, deleted: isDeleted = false, unseen = false, replies, onReply, resolved, noun = 'comment', onResolve, resolveHint, resolveRefused, onReopen, selected, onClick, onDelete, deleteNote, deleteRefused, menu, menuAfter, menuLabel, editLabel, deleteLabel, moreLabel = 'More actions', className, children } = props
396
+ const { author, about, files, reactions, isNew = false, urgent = false, own = false, editor, heading, deleted: isDeleted = false, unseen = false, replies, onReply, resolved, noun = 'comment', onResolve, resolveHint, resolveRefused, onReopen, selected, onClick, onDelete, deleteNote, deleteRefused, menu, menuAfter, menuLabel, editLabel, deleteLabel, moreLabel = 'More actions', className, children } = props
387
397
  // Not shown is drawn as deleted, in its own words.
388
398
  const deleted = isDeleted || unseen
389
399
  const readOnly = (props.readOnly ?? false) || deleted
@@ -462,9 +472,18 @@ export function ConversationCard(props: ConversationCardProps) {
462
472
  }}
463
473
  >
464
474
  {isEditing ? (
465
- <Editing author={author}>{editor(() => setEditing(false))}</Editing>
475
+ <Editing author={author} heading={heading}>
476
+ {editor(() => setEditing(false))}
477
+ </Editing>
466
478
  ) : (
467
479
  <div data-comment-body className="flex flex-col items-start px-2 pt-2">
480
+ {/* Where it was said, 8px over the face, inside the card (the Per-app prototype, 29 October). */}
481
+ {!!heading && (
482
+ // Faded clear of the strip, as the head's words are (useClearOfStrip).
483
+ <div className="w-full pb-2" style={wordsEnd === undefined ? undefined : { maskImage: fadeBefore(wordsEnd), WebkitMaskImage: fadeBefore(wordsEnd) }}>
484
+ {heading}
485
+ </div>
486
+ )}
468
487
  {deleted ? (
469
488
  <>
470
489
  {/* What it was on stays, where the words start: its replies still talk about that place (Leaf's; Katerina, 3 November: every app). */}
@@ -0,0 +1,52 @@
1
+ import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
2
+ import * as Stories from './ConversationHeading.stories'
3
+
4
+ <Meta of={Stories} />
5
+
6
+ # ConversationHeading
7
+
8
+ Which place a conversation is on, inside its card, when one list mixes conversations from several places.
9
+
10
+ <Canvas of={Stories.OnACard} />
11
+
12
+ ## When
13
+
14
+ - One list mixes this place's own conversations with conversations said on other places: each from elsewhere carries its place's icon and name at the top of its card, in the card's `heading`. This place's own carry none.
15
+
16
+ <Canvas of={Stories.WithWhatItIsOn} />
17
+
18
+ - A name longer than the column is cut.
19
+
20
+ <Canvas of={Stories.LongName} />
21
+
22
+ ## When not
23
+
24
+ - A conversation shown away from its place, with how it is related ("Mentioned in") above its card → **ConversationPlace**.
25
+ - A comment on a part of the place: what it is on goes in the card's `about` → **QuotedLine**. Both can be on one card: the place, then the author, then the words it is on.
26
+
27
+ ## How
28
+
29
+ ```tsx
30
+ import { ConversationCard, ConversationHeading, KindIcon } from '@estiva-app/ui'
31
+
32
+ <ConversationCard
33
+ author={author}
34
+ time={time}
35
+ heading={place ? <ConversationHeading icon={<KindIcon kind={kindOf(place)} />} name={place.title} onOpen={() => openPlace(place)} /> : undefined}
36
+ >
37
+ {words}
38
+ </ConversationCard>
39
+ ```
40
+
41
+ - `icon` is drawn in the face's column, so the name lines up with the author's. Give it 16px; it is hidden from screen readers, the name says it.
42
+ - `onOpen`, or `href`, makes the name a button or a link. A press on it opens the place, never the thread: the card leaves a press on a button or a link alone, and the rest of the card still opens the thread.
43
+ - A deleted comment keeps its heading: its replies still belong to that place.
44
+ - In a `ConversationLayout`, pass it on every card from elsewhere; the layout puts them in your order (time order, mixed with this place's own).
45
+
46
+ ## What it owns
47
+
48
+ Nothing. It only draws. Clicks and keys are yours.
49
+
50
+ ## Props
51
+
52
+ <Controls />
@@ -0,0 +1,44 @@
1
+ import type { Meta, StoryObj } from '@storybook/react-vite'
2
+ import { IconSquareRounded } from '@tabler/icons-react'
3
+ import { ConversationCard } from './ConversationCard'
4
+ import { Column, ONE, TWO, WORDS } from './conversation.examples'
5
+ import { ConversationHeading } from './ConversationHeading'
6
+ import { QuotedLine } from './QuotedLine'
7
+
8
+ /**
9
+ * Which place a conversation is on, inside its card, when one list mixes several places: the place's icon in the
10
+ * face's column, its name beside it, opening the place.
11
+ */
12
+ const meta = {
13
+ title: 'Conversation/ConversationHeading',
14
+ component: ConversationHeading,
15
+ parameters: { layout: 'padded' },
16
+ args: { name: 'Item one', icon: <IconSquareRounded size={16} stroke={1.5} />, onOpen: () => {} },
17
+ argTypes: { icon: { control: false } },
18
+ decorators: [(Story) => <Column>{Story()}</Column>],
19
+ render: (args) => (
20
+ <ConversationCard author={ONE} time="11:08 AM" heading={<ConversationHeading {...args} />} onClick={() => {}}>
21
+ {WORDS}
22
+ </ConversationCard>
23
+ ),
24
+ } satisfies Meta<typeof ConversationHeading>
25
+
26
+ export default meta
27
+ type Story = StoryObj<typeof meta>
28
+
29
+ /** On a card: the place above the author; its name opens the place, the rest of the card opens the thread. */
30
+ export const OnACard: Story = {}
31
+
32
+ /** On a comment about a part of the place: the place, then the author, then the words it is on. */
33
+ export const WithWhatItIsOn: Story = {
34
+ render: (args) => (
35
+ <ConversationCard author={TWO} time="Yesterday" heading={<ConversationHeading {...args} />} about={<QuotedLine words="the words this comment is on" />} onClick={() => {}}>
36
+ {WORDS}
37
+ </ConversationCard>
38
+ ),
39
+ }
40
+
41
+ /** A name longer than the column is cut. */
42
+ export const LongName: Story = {
43
+ args: { name: 'An item whose name runs on well past the width of the column it sits in' },
44
+ }
@@ -0,0 +1,81 @@
1
+ // @vitest-environment jsdom
2
+ /**
3
+ * What the ConversationHeading page claims, pinned: in a card's `heading`, the
4
+ * place's name sits above the author's, inside the card; pressing the name opens
5
+ * the place and never the thread; a deleted comment keeps its heading.
6
+ */
7
+ import { afterEach, describe, expect, it, vi } from 'vitest'
8
+ import { cleanup, render, screen } from '@testing-library/react'
9
+ import userEvent from '@testing-library/user-event'
10
+ import { ConversationCard } from './ConversationCard'
11
+ import { ConversationHeading } from './ConversationHeading'
12
+
13
+ afterEach(cleanup)
14
+
15
+ const ICON = <svg data-testid="icon" />
16
+
17
+ describe('ConversationHeading', () => {
18
+ it('draws the place above the author, inside the card', () => {
19
+ render(
20
+ <ConversationCard author={{ name: 'Person one' }} time="11:08 AM" heading={<ConversationHeading icon={ICON} name="Item one" onOpen={() => {}} />}>
21
+ The words
22
+ </ConversationCard>,
23
+ )
24
+ const place = screen.getByRole('button', { name: 'Item one' })
25
+ const author = screen.getByText('Person one')
26
+ expect(place.compareDocumentPosition(author) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy()
27
+ expect(place.closest('[data-comment-body]')).toBe(author.closest('[data-comment-body]'))
28
+ })
29
+
30
+ it('pressing the name opens the place, not the thread', async () => {
31
+ const onOpen = vi.fn()
32
+ const onClick = vi.fn()
33
+ render(
34
+ <ConversationCard author={{ name: 'Person one' }} time="11:08 AM" onClick={onClick} heading={<ConversationHeading icon={ICON} name="Item one" onOpen={onOpen} />}>
35
+ The words
36
+ </ConversationCard>,
37
+ )
38
+ await userEvent.click(screen.getByRole('button', { name: 'Item one' }))
39
+ expect(onOpen).toHaveBeenCalledTimes(1)
40
+ expect(onClick).not.toHaveBeenCalled()
41
+ await userEvent.click(screen.getByText('The words'))
42
+ expect(onClick).toHaveBeenCalledTimes(1)
43
+ })
44
+
45
+ it('a link: a plain click goes to the app to route, never to the thread; a modified click goes to the browser', () => {
46
+ const onOpen = vi.fn()
47
+ const onClick = vi.fn()
48
+ render(
49
+ <ConversationCard author={{ name: 'Person one' }} time="11:08 AM" onClick={onClick} heading={<ConversationHeading icon={ICON} name="Item one" href="/item/one" onOpen={onOpen} />}>
50
+ The words
51
+ </ConversationCard>,
52
+ )
53
+ const link = screen.getByRole('link', { name: 'Item one' })
54
+ const plain = new MouseEvent('click', { bubbles: true, cancelable: true, button: 0 })
55
+ link.dispatchEvent(plain)
56
+ expect(plain.defaultPrevented).toBe(true)
57
+ expect(onOpen).toHaveBeenCalledTimes(1)
58
+ const newTab = new MouseEvent('click', { bubbles: true, cancelable: true, button: 0, metaKey: true })
59
+ link.dispatchEvent(newTab)
60
+ expect(newTab.defaultPrevented).toBe(false)
61
+ expect(onOpen).toHaveBeenCalledTimes(1)
62
+ expect(onClick).not.toHaveBeenCalled()
63
+ })
64
+
65
+ it('with nothing to open, the name is plain text', () => {
66
+ render(<ConversationHeading icon={ICON} name="Item one" />)
67
+ expect(screen.getByText('Item one')).toBeTruthy()
68
+ expect(screen.queryByRole('button')).toBeNull()
69
+ expect(screen.queryByRole('link')).toBeNull()
70
+ })
71
+
72
+ it('a deleted comment keeps where it was said', () => {
73
+ render(
74
+ <ConversationCard author={{ name: 'Person one' }} time="11:08 AM" deleted heading={<ConversationHeading icon={ICON} name="Item one" />}>
75
+ The words
76
+ </ConversationCard>,
77
+ )
78
+ expect(screen.getByText('Item one')).toBeTruthy()
79
+ expect(screen.queryByText('The words')).toBeNull()
80
+ })
81
+ })
@@ -0,0 +1,55 @@
1
+ import type { ReactNode } from 'react'
2
+ import { isPlainClick } from './AppProvider'
3
+ import { cn } from './cn'
4
+
5
+ export interface ConversationHeadingProps {
6
+ /** What kind of place it is: a `KindIcon`, 16px. Drawn in the face's column, so the name lines up with the author's. */
7
+ icon: ReactNode
8
+ /** The place's name, cut to the column. */
9
+ name: string
10
+ /** Pressing the name opens the place. Without it (and without `href`) the name is plain text. */
11
+ onOpen?: () => void
12
+ /** Or a link to the place. With `onOpen` too, a plain click calls `onOpen` and the link only serves a new tab. */
13
+ href?: string
14
+ /** Placement only. */
15
+ className?: string
16
+ }
17
+
18
+ const NAME = '-mx-1 min-w-0 truncate rounded px-1 text-left text-h4 text-text-primary'
19
+
20
+ /**
21
+ * Where a conversation was said, above its first message, when one list mixes conversations from several places: the
22
+ * place's icon in the face's column and its name beside it, which opens the place. Goes in a `ConversationCard`'s
23
+ * `heading`, so it sits inside the card, as the Per-app prototype draws it (29 October). A press on the name opens the
24
+ * place, never the thread: the card leaves a press on a button or a link alone.
25
+ */
26
+ export function ConversationHeading({ icon, name, onOpen, href, className }: ConversationHeadingProps) {
27
+ const label = href ? (
28
+ <a
29
+ href={href}
30
+ // A plain click is the app's to route (onOpen); a new tab or window is the browser's.
31
+ onClick={(event) => {
32
+ if (!onOpen || !isPlainClick(event)) return
33
+ event.preventDefault()
34
+ onOpen()
35
+ }}
36
+ className={cn(NAME, 'hover:bg-bg-hover')}
37
+ >
38
+ {name}
39
+ </a>
40
+ ) : onOpen ? (
41
+ <button type="button" onClick={onOpen} className={cn(NAME, 'hover:bg-bg-hover')}>
42
+ {name}
43
+ </button>
44
+ ) : (
45
+ <span className={NAME}>{name}</span>
46
+ )
47
+ return (
48
+ <div data-conversation-heading className={cn('flex w-full items-center gap-2', className)}>
49
+ <span aria-hidden className="flex size-6 shrink-0 items-center justify-center text-text-secondary">
50
+ {icon}
51
+ </span>
52
+ {label}
53
+ </div>
54
+ )
55
+ }
@@ -1,6 +1,8 @@
1
1
  import type { Meta, StoryObj } from '@storybook/react-vite'
2
2
  import { useState, type ReactNode } from 'react'
3
3
  import { ConversationCard, ReplyCard } from './ConversationCard'
4
+ import { ConversationHeading } from './ConversationHeading'
5
+ import { KindIcon } from './KindIcon'
4
6
  import { ConversationLayout, type ConversationItem } from './ConversationLayout'
5
7
  import { ONE, SHORT, SOME, THREE, TWO, WORDS, WriteBox, YOU, useReactions } from './conversation.examples'
6
8
  import { ArchivedNotice } from './ArchivedNotice'
@@ -294,6 +296,64 @@ export const OneColumnBelow: Story = {
294
296
  },
295
297
  }
296
298
 
299
+ /** One list, three places: this place's own comments, and two other places' each under its name. */
300
+ const MIXED = [
301
+ { id: 'm1', author: ONE, time: '9:02 AM', words: 'A comment on this place itself: no name above it.', replies: 1 },
302
+ { id: 'm2', author: TWO, time: '9:40 AM', words: WORDS, replies: 2, place: 'Item one', quoted: 'the words this comment is on' },
303
+ { id: 'm3', author: THREE, time: '10:15 AM', words: 'Resolved on its own place, so it is resolved here too.', replies: 1, place: 'Item two', resolved: { by: 'You', note: 'Done.' } },
304
+ { id: 'm4', author: YOU, time: '11:30 AM', words: 'Another on this place, in time order with the rest.', replies: 0 },
305
+ { id: 'm5', author: ONE, time: '12:05 PM', words: 'A second comment on the first other place.', replies: 0, place: 'Item one' },
306
+ ]
307
+
308
+ function MixedItems({ open, setOpen }: { open: string | undefined; setOpen: (id: string | undefined) => void }) {
309
+ const [resolved, setResolved] = useState<Record<string, { by: string; note?: string } | undefined>>(() => Object.fromEntries(MIXED.map((c) => [c.id, c.resolved])))
310
+ const items: ConversationItem[] = MIXED.map((c) => ({
311
+ id: c.id,
312
+ card: (
313
+ <ConversationCard
314
+ author={c.author}
315
+ time={c.time}
316
+ heading={c.place ? <ConversationHeading icon={<KindIcon kind={c.place === 'Item one' ? 'file' : 'issue'} />} name={c.place} onOpen={() => {}} /> : undefined}
317
+ about={c.quoted ? <QuotedLine words={c.quoted} /> : undefined}
318
+ resolved={resolved[c.id]}
319
+ onResolve={(note) => setResolved((r) => ({ ...r, [c.id]: { by: 'You', note: note || undefined } }))}
320
+ onReopen={() => setResolved((r) => ({ ...r, [c.id]: undefined }))}
321
+ replies={c.replies ? { count: c.replies, faces: [TWO, YOU], last: '11:52 AM' } : undefined}
322
+ >
323
+ {c.words}
324
+ </ConversationCard>
325
+ ),
326
+ thread: (
327
+ <Thread start={{ author: c.author, time: c.time, words: c.words }} onClose={() => setOpen(undefined)} box={<WriteBox />}>
328
+ {c.replies ? <Replies /> : undefined}
329
+ </Thread>
330
+ ),
331
+ }))
332
+ return <ConversationLayout threads="beside" items={items} open={open} onOpenChange={setOpen} box={<WriteBox label="Message" />} />
333
+ }
334
+
335
+ /**
336
+ * Two columns mixing several places: comments said elsewhere sit in time order with this place's own, each under its
337
+ * place's name (`ConversationHeading` in the card's `heading`). A reply opened from one is that place's thread.
338
+ */
339
+ export const SeveralPlaces: Story = {
340
+ name: 'Several places',
341
+ render: function Render() {
342
+ const [open, setOpen] = useState<string | undefined>()
343
+ return <MixedItems open={open} setOpen={setOpen} />
344
+ },
345
+ }
346
+
347
+ /** The same at phone width: the place's name is cut to the column. */
348
+ export const SeveralPlacesNarrow: Story = {
349
+ name: 'Several places, narrow',
350
+ globals: { viewport: { value: 'mobile1', isRotated: false } },
351
+ render: function Render() {
352
+ const [open, setOpen] = useState<string | undefined>()
353
+ return <MixedItems open={open} setOpen={setOpen} />
354
+ },
355
+ }
356
+
297
357
  /** Nobody has commented yet. */
298
358
  export const Empty: Story = {
299
359
  render: () => (
@@ -35,6 +35,9 @@ import { ConversationCard, QuotedLine } from '@estiva-app/ui'
35
35
  - Two lines at most; the whole words are in the tooltip.
36
36
  - A part with no words, a picture or a block: `label`, its name in your words, on the grey: the yellow is only for words still in the page.
37
37
  - Made for the card's `about`: the card puts it under the name, where the words start.
38
+ - Read away from the page it quotes (another app, a list of comments from several pages): `href`, where the words are in that page, and the words are a **Link** (`quiet`) that opens it there, in place through the app's `navigate`, or in a new tab when `external`; a press on it never opens the card's thread around it. Beside the page itself, none.
39
+
40
+ <Canvas of={Stories.Linked} />
38
41
 
39
42
  ## What it owns
40
43
 
@@ -23,6 +23,9 @@ export const Reworded: Story = { name: 'Words changed', args: { state: 'reworded
23
23
  /** The part was deleted from the page: the words struck through, and "Deleted from the page". */
24
24
  export const Gone: Story = { name: 'Part deleted', args: { state: 'gone' } }
25
25
 
26
+ /** Read away from the page it quotes: the words open that page where they are. */
27
+ export const Linked: Story = { name: 'Words that open the page', args: { href: 'https://example.com/page#block-1' } }
28
+
26
29
  /** On a part with no words of its own, a picture: its name, in the app's words. */
27
30
  export const Part: Story = { name: 'No words', args: { words: undefined, label: 'Picture: plan-sketch.png' } }
28
31
 
@@ -40,4 +40,17 @@ describe('QuotedLine', () => {
40
40
  expect(mark.className).toMatch(/\bbg-bg-inset\b/)
41
41
  expect(mark.className).not.toMatch(/\bline-through\b/)
42
42
  })
43
+
44
+ // A reader in another app reaches the sentence in one click, as the part card's link did (Miky, 10 November).
45
+ it('makes the words the link to where they are in their file, when given one', () => {
46
+ render(<QuotedLine words="brass fitting" href="https://ship.example/issue/x#block-b1" external />)
47
+ const link = screen.getByRole('link', { name: 'brass fitting' })
48
+ expect(link.getAttribute('href')).toBe('https://ship.example/issue/x#block-b1')
49
+ expect(link.getAttribute('target')).toBe('_blank')
50
+ })
51
+
52
+ it('draws the words as no link where the file is beside them', () => {
53
+ render(<QuotedLine words="brass fitting" />)
54
+ expect(screen.queryByRole('link')).toBeNull()
55
+ })
43
56
  })
@@ -1,4 +1,5 @@
1
1
  import { cn } from './cn'
2
+ import { Link } from './Link'
2
3
  import { WithTooltip } from './Tooltip'
3
4
 
4
5
  export interface QuotedLineProps {
@@ -8,6 +9,13 @@ export interface QuotedLineProps {
8
9
  state?: 'here' | 'reworded' | 'gone'
9
10
  /** A part with no words, a picture or a whole block: what it is, in the app's words ("Picture: plan.png"). */
10
11
  label?: string
12
+ /**
13
+ * Where the words are in their file, when the reader is not looking at it: the words open it there. The page that
14
+ * shows the file beside its comments gives none. Navigation is yours, as for every `Link`.
15
+ */
16
+ href?: string
17
+ /** `href` is another app's: it opens in a new tab. */
18
+ external?: boolean
11
19
  }
12
20
 
13
21
  const SINCE = { reworded: 'Changed since', gone: 'Deleted from the page' } as const
@@ -16,17 +24,25 @@ const SINCE = { reworded: 'Changed since', gone: 'Deleted from the page' } as co
16
24
  * What a comment on a part of the page is on: its words, two lines at most, in the page's own highlight, so the two
17
25
  * read as one. ConversationCard puts it under the name, above the comment's words ("above the message, not above the
18
26
  * person": Katerina, 1 November). Words changed since or deleted lose the highlight and say so; a part with no words
19
- * gives its name, on the grey: it is not words of the page.
27
+ * gives its name, on the grey: it is not words of the page. With `href`, the words are the way to them in their file
28
+ * (Miky, 10 November: a reader in another app reaches the sentence in one click, as the part card's link did).
20
29
  */
21
- export function QuotedLine({ words, state = 'here', label }: QuotedLineProps) {
30
+ export function QuotedLine({ words, state = 'here', label, href, external }: QuotedLineProps) {
22
31
  const shown = words ?? label ?? ''
23
32
  // The page's yellow only for words still in it; a part's name is not words of the page, so it takes the grey (Katerina, 3 November).
24
33
  const inThePage = !!words && state === 'here'
34
+ const mark = <mark className={cn('rounded-sm px-0.5 text-text-primary [box-decoration-break:clone]', inThePage ? 'bg-warning-muted' : 'bg-bg-inset text-text-secondary', state === 'gone' && 'line-through')}>{shown}</mark>
25
35
  return (
26
36
  <div data-quoted={words ? state : 'part'} className="flex w-full min-w-0 flex-col gap-0.5">
27
37
  <WithTooltip label={shown} wrapperClassName="flex min-w-0">
28
38
  <p className="line-clamp-2 text-caption text-text-secondary">
29
- <mark className={cn('rounded-sm px-0.5 text-text-primary [box-decoration-break:clone]', inThePage ? 'bg-warning-muted' : 'bg-bg-inset text-text-secondary', state === 'gone' && 'line-through')}>{shown}</mark>
39
+ {href ? (
40
+ <Link href={href} variant="quiet" external={external}>
41
+ {mark}
42
+ </Link>
43
+ ) : (
44
+ mark
45
+ )}
30
46
  </p>
31
47
  </WithTooltip>
32
48
  {state !== 'here' && <span className="text-caption italic text-text-muted">{SINCE[state]}</span>}
package/src/index.ts CHANGED
@@ -145,6 +145,7 @@ export { ConversationLayout, type ConversationItem, type ConversationLayoutProps
145
145
  export { caretOnOpen } from './threadCard'
146
146
  // Where a two-column conversation was left, for the app's "New" line; and the layout's word to its box that the reader's own comment is on its way (CommentBox reads it, from the editor's bundle).
147
147
  export { useLeftAt, sendsInLayout } from './conversationScroll'
148
+ export { ConversationHeading, type ConversationHeadingProps } from './ConversationHeading'
148
149
  export { ConversationMenu, type ConversationMenuProps } from './ConversationMenu'
149
150
  export { ConversationPlace, type ConversationPlaceProps } from './ConversationPlace'
150
151
  export { EditedMarker, type EditedMarkerProps } from './EditedMarker'
@@ -48,19 +48,19 @@ describe('the registry builds', () => {
48
48
  expect(registry.entries.map((one) => one.name).sort()).toEqual(values.map((one) => one.name).sort())
49
49
  })
50
50
 
51
- it('counts 250 names over 127 files: 165 components, 78 helpers and 7 hooks (FollowSwitch, LevelIcon and WhoFollowsDialog, how you follow a place and who follows it (TEA-6), on 6 November; goneWords and GONE_CLOSED, what stands in a gone comment’s place and under its thread in every app (ONE-9), on 6 November; DeletedNotice and NoAccessNotice, the cards on a deleted file and on one you cannot open (ALO-4), on 3 November; useFormBusy, whether a Form around it is sending, read by the editor’s DocumentField from the main entry, in the review of 2 November; useLeftAt, sendsInLayout, useSeenOnScreen, showInConversation and showInConversationWhenDrawn, where a conversation scrolls, what was seen and a link landing on a comment, moved from Peek for every app, on 2 November; useRememberedOpen, the fold a section remembers, read by the app, and NAV_TREE_PENDING_MS and isPlainClick, Peek’s Folder timer and plain-click check, moved in, on 2 November; FormDialog, MoveDialog and ArchiveDialog, the dialogs Peek wired by hand, on 2 November; ConversationPlace, the line saying where a comment was said, and DocumentField, a rich-text field of a form, moved from Peek, on 2 November; ArchivedNotice, the card on an archived file, from Peek, Ship and Leaf, on 31 October; caretOnOpen, the box at a thread’s foot taking the caret when a ConversationLayout opens it, without scrolling, on 31 October; the conversation from Peek for every app, with PageHeader and PinnedComment, on 31 October, and ResolutionNote and ResolutionHistory gone with the resolved looks not picked, on 1 November; useSidebarFold, a folded sidebar kept folded in every app, on 31 October; cardShapeMemory, a card’s last shape on this device, lifted from Peek and Ship for Leaf, and ReferenceCards and useReferenceCards gone with their deprecated page, in the widget review, on 30 October; inTheBox, a card or part in a box being written in, on the files’ fill and in words, on 29 October; archivedLine, the line on an archived file in every app (PEEKM-2), on 23 October; keepCommentBoxWarm, a box built ahead, exported as 0.84.0 promised (PEEKM-1), on 21 October;linkedFrom and linkStateFrom, one card for a file in every app (5ebf2756), on 21 October; ComposeBox, ComposeKeys and COMPOSE_EDITOR_CLASSES gone into CommentBox’s own frame (one box), on 21 October; LinkPlaces with linkPlaceAt and staysChip, a link in a document drawn where it sits (WBD-4), on 20 October; DocumentEditor, one document editor for every app, and PersonReference, `@` in a document (WBD-3), on 20 October; toggleTableHeaderRow, a table’s header row on and off (LEAF-12), on 19 October;EntryShell, the screen while nobody is signed in, moved from Peek (AUT-3), on 17 October; CommentBox with commentBoxRows, and ReactionRow with AddReactionButton and whoReacted, the shared comment box and reaction row (COMM-2), on 17 October; the link widgets — LinkChip, LinkRow, LinkCard, CardUnder, PartCard, LinkPreview and their parts, with useCanHover, chosenOf, loadingShapeOf and unavailableMemory — from the Widgets 2 prototype, on 16 October; InlineText, a title or the line under it edited where it stands (SUM-4), on 16 October; ComposeBox with ComposeKeys and its classes, CommentHighlights with its five helpers, and keepSelection and releaseSelection, from the Leaf prototype (LEAF-4), on 16 October;NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, moveBlock and blockDropCursor, the drop in the gutter, on 5 October, MembersPill and MembersDialog, moved from Peek (SHI-31), on 6 October, ShowMore on 7 October, AppProvider on 8 October, and KindIcon, thingKindOf and PastedImages with its two helpers, moved from Peek, on 8 October; CodeBlockColours, the coloured code block of the editor, on 9 October; Checklist, Callout, isChecklistTick and calloutLook (RIC-19) on 13 October; EditorTableControls and its four actions (RIC-21) on 13 October; ReferenceCards, useReferenceCards and its three helpers, the card a chip in a document asks for, on 14 October; LinkChips and its two helpers, a URL in a document read as its chip, on 14 October; ReferenceMenu, ReferenceMenuView and three helpers, the menu of a chip while writing, on 14 October; PastedMarkdown, markdown pasted as the blocks it spells (LEAF-10), on 15 October; turnIntoRows, turnListInto and turnQuoteInto, the block menu’s Turn into for a list and a quote (LEAF-11), on 15 October)', () => {
51
+ it('counts 251 names over 128 files: 166 components, 78 helpers and 7 hooks (ConversationHeading, which place a comment is on in a list mixing several places (TOPI-2), on 9 November; FollowSwitch, LevelIcon and WhoFollowsDialog, how you follow a place and who follows it (TEA-6), on 6 November; goneWords and GONE_CLOSED, what stands in a gone comment’s place and under its thread in every app (ONE-9), on 6 November; DeletedNotice and NoAccessNotice, the cards on a deleted file and on one you cannot open (ALO-4), on 3 November; useFormBusy, whether a Form around it is sending, read by the editor’s DocumentField from the main entry, in the review of 2 November; useLeftAt, sendsInLayout, useSeenOnScreen, showInConversation and showInConversationWhenDrawn, where a conversation scrolls, what was seen and a link landing on a comment, moved from Peek for every app, on 2 November; useRememberedOpen, the fold a section remembers, read by the app, and NAV_TREE_PENDING_MS and isPlainClick, Peek’s Folder timer and plain-click check, moved in, on 2 November; FormDialog, MoveDialog and ArchiveDialog, the dialogs Peek wired by hand, on 2 November; ConversationPlace, the line saying where a comment was said, and DocumentField, a rich-text field of a form, moved from Peek, on 2 November; ArchivedNotice, the card on an archived file, from Peek, Ship and Leaf, on 31 October; caretOnOpen, the box at a thread’s foot taking the caret when a ConversationLayout opens it, without scrolling, on 31 October; the conversation from Peek for every app, with PageHeader and PinnedComment, on 31 October, and ResolutionNote and ResolutionHistory gone with the resolved looks not picked, on 1 November; useSidebarFold, a folded sidebar kept folded in every app, on 31 October; cardShapeMemory, a card’s last shape on this device, lifted from Peek and Ship for Leaf, and ReferenceCards and useReferenceCards gone with their deprecated page, in the widget review, on 30 October; inTheBox, a card or part in a box being written in, on the files’ fill and in words, on 29 October; archivedLine, the line on an archived file in every app (PEEKM-2), on 23 October; keepCommentBoxWarm, a box built ahead, exported as 0.84.0 promised (PEEKM-1), on 21 October;linkedFrom and linkStateFrom, one card for a file in every app (5ebf2756), on 21 October; ComposeBox, ComposeKeys and COMPOSE_EDITOR_CLASSES gone into CommentBox’s own frame (one box), on 21 October; LinkPlaces with linkPlaceAt and staysChip, a link in a document drawn where it sits (WBD-4), on 20 October; DocumentEditor, one document editor for every app, and PersonReference, `@` in a document (WBD-3), on 20 October; toggleTableHeaderRow, a table’s header row on and off (LEAF-12), on 19 October;EntryShell, the screen while nobody is signed in, moved from Peek (AUT-3), on 17 October; CommentBox with commentBoxRows, and ReactionRow with AddReactionButton and whoReacted, the shared comment box and reaction row (COMM-2), on 17 October; the link widgets — LinkChip, LinkRow, LinkCard, CardUnder, PartCard, LinkPreview and their parts, with useCanHover, chosenOf, loadingShapeOf and unavailableMemory — from the Widgets 2 prototype, on 16 October; InlineText, a title or the line under it edited where it stands (SUM-4), on 16 October; ComposeBox with ComposeKeys and its classes, CommentHighlights with its five helpers, and keepSelection and releaseSelection, from the Leaf prototype (LEAF-4), on 16 October;NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, moveBlock and blockDropCursor, the drop in the gutter, on 5 October, MembersPill and MembersDialog, moved from Peek (SHI-31), on 6 October, ShowMore on 7 October, AppProvider on 8 October, and KindIcon, thingKindOf and PastedImages with its two helpers, moved from Peek, on 8 October; CodeBlockColours, the coloured code block of the editor, on 9 October; Checklist, Callout, isChecklistTick and calloutLook (RIC-19) on 13 October; EditorTableControls and its four actions (RIC-21) on 13 October; ReferenceCards, useReferenceCards and its three helpers, the card a chip in a document asks for, on 14 October; LinkChips and its two helpers, a URL in a document read as its chip, on 14 October; ReferenceMenu, ReferenceMenuView and three helpers, the menu of a chip while writing, on 14 October; PastedMarkdown, markdown pasted as the blocks it spells (LEAF-10), on 15 October; turnIntoRows, turnListInto and turnQuoteInto, the block menu’s Turn into for a list and a quote (LEAF-11), on 15 October)', () => {
52
52
  // The reconciliation GATES.md §24 explains. If this changes, that changes.
53
53
  // The `EDITOR_EXTENSIONS` count as components by their names; they are
54
54
  // editor extensions, documented on SelectionToolbar's, BlockNodes' and
55
55
  // ComposerTriggers' pages.
56
56
  const kinds = registry.entries.reduce<Record<string, number>>((all, one) => ({ ...all, [one.kind]: (all[one.kind] ?? 0) + 1 }), {})
57
- expect(kinds).toEqual({ component: 165, helper: 78, hook: 7 })
58
- expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(127)
57
+ expect(kinds).toEqual({ component: 166, helper: 78, hook: 7 })
58
+ expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(128)
59
59
  })
60
60
 
61
61
  it('gives every entry a purpose, from its own page or from the comment above it', () => {
62
62
  expect(registry.entries.filter((one) => one.purpose.trim() === '')).toEqual([])
63
- expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(114)
63
+ expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(115)
64
64
  expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(136)
65
65
  })
66
66
 
@@ -99,6 +99,7 @@ The same conversation in every app; only its colours are each app's.
99
99
  | Where the comments sit, and where a thread opens | **ConversationLayout** — two columns, the thread beside them; or one 384px column, the thread under its comment |
100
100
  | One comment | **ConversationCard** — the words, files, cards, reactions, replies row, the actions on hover and the ⋯ menu |
101
101
  | Where a conversation shown away from its place was said, above its card | **ConversationPlace** — how it is related and the place, in your words |
102
+ | Which place each conversation is on, in one list that mixes several places | **ConversationHeading** — the place's icon and name inside the card, in its `heading`, opening the place |
102
103
  | One reply in a thread | **ReplyCard** — a comment's pieces, without replies of its own or Resolve |
103
104
  | A comment's replies and the box to write one | **Thread** — in the right column under its header, or under its comment |
104
105
  | The way into a thread | **RepliesRow** — faces, "2 replies", the last time and how many are new ("2 new") |