@estiva-app/ui 0.74.0 → 0.75.0

package/src/LinkCard.tsx

@@ -0,0 +1,209 @@
+/**
+ * A link's card: what a row cannot hold. The header is the row's line (icon
+ * and title as the link; a ring or faces in the corner), then the key and
+ * what it is in, its summary, the items inside it, the newest thing said in
+ * it, and a footer: the pickers and the conversation count, or who and when.
+ * Words a person wrote draw as themselves, with their face and the time.
+ *
+ * While it loads it holds the card's own height, so what is around it does
+ * not jump; not available is one line.
+ */
+import { Avatar } from './Avatar'
+import { AvatarGroup } from './AvatarGroup'
+import { Card } from './Card'
+import { Link } from './Link'
+import type { Linked, LinkedKind, LinkState, LoadingShape } from './linked'
+import { CommentCount, LinkedIcon, LinkKey, LinkPickers, ProgressRing, StatusMark } from './LinkParts'
+import { LinkUnavailable } from './LinkRow'
+import { SkeletonBar } from './Skeleton'
+
+export interface LinkCardProps {
+  link: LinkState
+  /** The values read as words, never pickers: the hover preview. */
+  readOnly?: boolean
+  /** No frame of its own: inside a box that draws one, as the hover preview's. */
+  bare?: boolean
+}
+
+export function LinkCard({ link, readOnly = false, bare = false }: LinkCardProps) {
+  if (link.state === 'loading') return <LinkCardLoading kind={link.kind} shape={link.shape} />
+  if (link.state === 'unavailable') return <LinkUnavailable kind={link.kind} noun={link.noun} openIn={link.openIn} />
+  const { linked } = link
+  const body = linked.kind === 'message' && linked.author ? <SaidBody linked={linked} /> : <CardBody linked={linked} readOnly={readOnly} />
+  if (bare) return <div className="flex flex-col gap-2 p-3">{body}</div>
+  return (
+    <Card fill="inset" className="flex flex-col gap-2 p-3">
+      {body}
+    </Card>
+  )
+}
+
+function CardBody({ linked, readOnly }: { linked: Linked; readOnly: boolean }) {
+  return (
+    <>
+      <div className="flex min-h-[19.6px] items-center gap-2">
+        {/* The icon opens it too, so the target is larger than the words. */}
+        <span className="flex min-w-0 flex-1 text-body-2-strong text-text-primary">
+          <Link href={linked.href} variant="quiet" className="flex min-w-0 flex-1 items-center gap-2">
+            <LinkedIcon kind={linked.kind} />
+            <span className="truncate">{linked.title}</span>
+          </Link>
+        </span>
+        {linked.done && <ProgressRing done={linked.done.done} total={linked.done.total} />}
+        {linked.members && <AvatarGroup members={linked.members} size={16} />}
+      </div>
+      {(linked.key || linked.subtitle) && <p className="-mt-1 pl-6 text-caption text-text-secondary">{[linked.key, linked.subtitle].filter(Boolean).join(' · ')}</p>}
+      {linked.summary && <p className="line-clamp-2 text-body-2 text-text-secondary">{linked.summary}</p>}
+      {linked.children && linked.children.length > 0 && (
+        <div className="flex flex-col divide-y divide-border-subtle rounded-md border border-border-subtle leaf:divide-border-strong leaf:border-border-strong">
+          {linked.children.map((child) => (
+            <div key={child.id} className="relative flex h-8 items-center gap-2 px-2 hover:bg-bg-active">
+              {/* The status is the row's icon: a list needs no kind icon on every row. */}
+              <StatusMark status={child.status} />
+              {child.key && <LinkKey>{child.key}</LinkKey>}
+              {/* Each opens on its own; the link covers its row. */}
+              <span className="contents text-body-2 text-text-primary">
+                <Link href={child.href} variant="quiet" cover truncate className="min-w-0 flex-1">
+                  {child.title}
+                </Link>
+              </span>
+              {child.owner ? <Avatar name={child.owner.name} src={child.owner.picture} size={16} /> : <span className="size-4 shrink-0" aria-hidden />}
+            </div>
+          ))}
+        </div>
+      )}
+      {linked.latest && (
+        <div className="flex flex-col gap-1">
+          {/* "Latest" in words: the card follows it, so this is not necessarily what the link was sent about. */}
+          <span className="text-caption text-text-muted">Latest conversation</span>
+          <div className="flex gap-2 rounded-md border border-border-subtle p-2 leaf:border-border-strong">
+            <Avatar name={linked.latest.author.name} src={linked.latest.author.picture} size={16} />
+            <div className="min-w-0 flex-1">
+              <div className="flex items-baseline gap-2 text-caption">
+                <span className="text-text-primary">{linked.latest.author.name}</span>
+                <span className="text-text-muted">{linked.latest.at}</span>
+              </div>
+              <p className="line-clamp-2 text-body-2 text-text-secondary">{linked.latest.body}</p>
+            </div>
+          </div>
+        </div>
+      )}
+      <div className="flex min-h-6 items-center gap-2 border-t border-border-subtle pt-2 leaf:border-border-strong">
+        {(linked.status || linked.owner) && <LinkPickers status={linked.status} owner={linked.owner} ownerLabel={linked.ownerLabel} readOnly={readOnly} />}
+        {/* Faces only: names would not fit once several people wrote it. */}
+        {linked.authors ? (
+          <span className="flex min-w-0 items-center gap-2 text-caption text-text-secondary">
+            <AvatarGroup members={linked.authors} size={16} />
+            {linked.updated && <span className="shrink-0">{linked.updated}</span>}
+          </span>
+        ) : (
+          !linked.status && !linked.owner && linked.updated && <span className="text-caption text-text-secondary">Updated {linked.updated}</span>
+        )}
+        {linked.conversation && (
+          <span className="ml-auto flex">
+            <CommentCount conversation={linked.conversation} noun={linked.conversation.noun} />
+          </span>
+        )}
+      </div>
+    </>
+  )
+}
+
+/** Words a person wrote, linked: their face, their name, the time as the link, and the words. */
+function SaidBody({ linked }: { linked: Linked }) {
+  const author = linked.author!
+  return (
+    <>
+      <div className="flex items-center gap-2">
+        <Avatar name={author.name} src={author.picture} size={24} />
+        <span className="text-body-2-strong text-text-primary">{author.name}</span>
+        <span className="text-caption text-text-muted">
+          <Link href={linked.href} variant="quiet">
+            {linked.updated ?? 'Open'}
+          </Link>
+        </span>
+      </div>
+      <p className="line-clamp-4 text-body-2 text-text-primary">{linked.body ?? linked.title}</p>
+    </>
+  )
+}
+
+/** Each kind's usual card, for a placeholder when the app remembers nothing of it. */
+const KIND_SHAPE: Record<LinkedKind, LoadingShape> = {
+  issue: { subtitle: true, summary: true, footer: 'pickers' },
+  project: { subtitle: false, summary: true, rows: 3, ring: true, footer: 'pickers' },
+  topic: { summary: true, latest: true, footer: 'line' },
+  page: { subtitle: true, summary: true, footer: 'people' },
+  file: { summary: false, footer: 'line' },
+  message: { summary: true, footer: 'none' },
+}
+
+export interface LinkCardLoadingProps {
+  kind: LinkedKind
+  /** What the card will hold (`loadingShapeOf` from the last time it drew); the kind's usual card otherwise. */
+  shape?: LoadingShape
+}
+
+/** The card it will become, drawn in bars at the card's own height. */
+export function LinkCardLoading({ kind, shape }: LinkCardLoadingProps) {
+  const { subtitle = false, summary = true, rows = 0, latest = false, ring = false, footer = 'line' } = shape ?? KIND_SHAPE[kind]
+  return (
+    <div className="animate-skeleton-in" aria-busy>
+      <Card fill="inset" aria-hidden className="flex flex-col gap-2 p-3">
+        <div className="flex h-[19.6px] items-center gap-2">
+          <LinkedIcon kind={kind} />
+          <SkeletonBar on="inset" className="h-3.5 w-1/2" />
+          {ring && <SkeletonBar on="inset" shape="round" className="ml-auto size-4" />}
+        </div>
+        {subtitle && (
+          <div className="-mt-1 flex h-[14.4px] items-center pl-6">
+            <SkeletonBar on="inset" className="h-2.5 w-20" />
+          </div>
+        )}
+        {summary && (
+          <div className="flex h-[19.6px] items-center">
+            <SkeletonBar on="inset" className="h-3 w-4/5" />
+          </div>
+        )}
+        {rows > 0 && (
+          <div className="flex flex-col divide-y divide-border-subtle rounded-md border border-border-subtle leaf:divide-border-strong leaf:border-border-strong">
+            {Array.from({ length: rows }, (_, i) => (
+              <div key={i} className="flex h-8 items-center px-2">
+                <SkeletonBar on="inset" className="h-3 w-1/3" />
+              </div>
+            ))}
+          </div>
+        )}
+        {latest && (
+          <div className="flex flex-col gap-1">
+            <div className="flex h-[14.4px] items-center">
+              <SkeletonBar on="inset" className="h-2.5 w-28" />
+            </div>
+            <div className="flex h-[71.6px] flex-col justify-center gap-2 rounded-md border border-border-subtle p-2 leaf:border-border-strong">
+              <SkeletonBar on="inset" className="h-2.5 w-24" />
+              <SkeletonBar on="inset" className="h-3 w-full" />
+              <SkeletonBar on="inset" className="h-3 w-3/5" />
+            </div>
+          </div>
+        )}
+        {footer !== 'none' && (
+          <div className="flex min-h-6 items-center gap-2 border-t border-border-subtle pt-2 leaf:border-border-strong">
+            {footer === 'pickers' ? (
+              <>
+                <SkeletonBar on="inset" shape="control" className="h-6 w-24" />
+                <SkeletonBar on="inset" shape="control" className="h-6 w-28" />
+              </>
+            ) : footer === 'people' ? (
+              <>
+                <SkeletonBar on="inset" shape="round" className="size-4" />
+                <SkeletonBar on="inset" className="h-3 w-40" />
+              </>
+            ) : (
+              <SkeletonBar on="inset" className="h-3 w-40" />
+            )}
+          </div>
+        )}
+      </Card>
+    </div>
+  )
+}

package/src/LinkChip.mdx

@@ -0,0 +1,51 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as LinkChipStories from './LinkChip.stories'
+
+<Meta of={LinkChipStories} />
+
+# LinkChip
+
+A link in a sentence: its icon, its key, its title cut short, and its status as a shape.
+
+<Canvas of={LinkChipStories.InASentence} />
+
+## When
+
+- **ready** — a link the app has looked up. Hovering it shows its card (**LinkPreview**); a tap or a click opens it.
+- **loading** — still being looked up: the icon, which the address already says, and a bar.
+- **unavailable** — deleted, or not the reader's to see. Both say "Item, not available" in the app's word for it.
+- `preview={false}` — no card on hover, where a card would cover what the reader is choosing from.
+
+<Canvas of={LinkChipStories.EachKind} />
+
+## When not
+
+- A link alone on its line → **LinkRow**.
+- The one card under a piece of text → **CardUnder**.
+- A person, a place or a label with no lookup behind it → **InlineChip**.
+
+## How
+
+```tsx
+import { LinkChip, type LinkState } from '@estiva-app/ui'
+
+// The app looks the link up and hands in where that stands.
+const link: LinkState = found ? { state: 'ready', linked: found } : gone ? { state: 'unavailable', kind: 'issue', noun: 'Item' } : { state: 'loading', kind: 'issue' }
+<LinkChip link={link} />
+```
+
+- **The app looks it up; the chip draws.** `linked` (`Linked`, from `@estiva-app/ui`) carries the words, the `href`, the status and the owner as the app's lookup found them. The chip fetches nothing.
+- `linked.href` opens it. An address in this app goes through `AppProvider`'s `navigate`, so the page does not reload.
+- Words a person wrote (`kind: 'message'` with an `author`) lead with their face and read "Name: words".
+
+## What it owns
+
+| It does | So you never write |
+|---|---|
+| Shows the card on hover, and none on a screen that cannot hover | a hover card of your own, a touch check |
+| Cuts a long title short | a truncation of your own |
+| Says "not available" in words, quieter than a link | a missing-reference chip of your own |
+
+## Props
+
+<Controls of={LinkChipStories.InASentence} />

package/src/LinkChip.stories.tsx

@@ -0,0 +1,40 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { LinkChip } from './LinkChip'
+import { GROUP, ITEM, LOADING, PAGE, PLACE, ready, SAID, UNAVAILABLE } from './linked.examples'
+
+const meta = {
+  title: 'Components/LinkChip',
+  component: LinkChip,
+  parameters: { layout: 'padded' },
+  args: { link: ready(ITEM) },
+} satisfies Meta<typeof LinkChip>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** In a sentence. Hover it for its card. */
+export const InASentence: Story = {
+  render: (args) => (
+    <p className="max-w-[560px] text-body-2 text-text-primary">
+      A sentence that links <LinkChip {...args} /> in the middle of its words, and goes on after it.
+    </p>
+  ),
+}
+
+/** Every kind, by its icon; words a person wrote lead with their face. */
+export const EachKind: Story = {
+  render: () => (
+    <p className="max-w-[560px] text-body-2 leading-7 text-text-primary">
+      <LinkChip link={ready(ITEM)} /> <LinkChip link={ready(GROUP)} /> <LinkChip link={ready(PLACE)} /> <LinkChip link={ready(PAGE)} /> <LinkChip link={ready(SAID)} />
+    </p>
+  ),
+}
+
+/** Still being looked up: the icon, known from the address, and a bar. */
+export const Loading: Story = { args: { link: LOADING } }
+
+/** Deleted, or not this reader's to see: said in words. */
+export const NotAvailable: Story = { args: { link: UNAVAILABLE } }
+
+/** No card on hover: where a card would cover what the reader is choosing from. */
+export const WithoutPreview: Story = { args: { preview: false } }

package/src/LinkChip.test.tsx

@@ -0,0 +1,83 @@
+// @vitest-environment jsdom
+/**
+ * What the LinkChip and LinkPreview pages claim, pinned: what each state says,
+ * where the chip leads, and that a screen that cannot hover gets no preview.
+ */
+import { act, cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { LinkChip } from './LinkChip'
+import { ITEM, LOADING, ready, SAID, UNAVAILABLE } from './linked.examples'
+
+/** A screen that can hover, or one that cannot (a phone, a tablet). */
+function screenThatCanHover(canHover: boolean) {
+  vi.stubGlobal('matchMedia', (query: string) => ({
+    matches: query === '(hover: hover)' ? canHover : false,
+    media: query,
+    addEventListener: () => {},
+    removeEventListener: () => {},
+  }))
+}
+
+beforeEach(() => {
+  vi.useFakeTimers({ shouldAdvanceTime: true })
+})
+
+afterEach(() => {
+  cleanup()
+  vi.useRealTimers()
+  vi.unstubAllGlobals()
+})
+
+/** Rest the pointer on the chip past the preview's delay. */
+async function hoverChip(name: RegExp) {
+  const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime })
+  await user.hover(screen.getByRole('link', { name }))
+  await act(async () => {
+    vi.advanceTimersByTime(1000)
+  })
+}
+
+describe('LinkChip', () => {
+  it('leads to what it links, with its key and title', () => {
+    render(<LinkChip link={ready(ITEM)} preview={false} />)
+    const link = screen.getByRole('link', { name: /ABC-2/ })
+    expect(link.getAttribute('href')).toBe('#item')
+    expect(link.textContent).toContain(ITEM.title)
+  })
+
+  it('says a person’s words after their name', () => {
+    render(<LinkChip link={ready(SAID)} preview={false} />)
+    expect(screen.getByRole('link').textContent).toContain(`Person one: ${SAID.body}`)
+  })
+
+  it('while it loads, is busy and leads nowhere yet', () => {
+    const { container } = render(<LinkChip link={LOADING} />)
+    expect(container.querySelector('[aria-busy="true"]')).not.toBeNull()
+    expect(screen.queryByRole('link')).toBeNull()
+  })
+
+  it('says “not available” in words, and leads nowhere', () => {
+    render(<LinkChip link={UNAVAILABLE} />)
+    expect(screen.getByText('Item, not available')).toBeTruthy()
+    expect(screen.queryByRole('link')).toBeNull()
+  })
+
+  it('shows its card, read only, when the pointer rests on it', async () => {
+    screenThatCanHover(true)
+    render(<LinkChip link={ready(ITEM)} />)
+    await hoverChip(/ABC-2/)
+    expect(screen.getByText(ITEM.summary!)).toBeTruthy()
+    // Read only: the values are words, never pickers, though this reader may change them.
+    expect(screen.queryByRole('combobox')).toBeNull()
+    expect(screen.getByText('Person one')).toBeTruthy()
+  })
+
+  it('shows no card on a screen that cannot hover, where a tap opens it', async () => {
+    screenThatCanHover(false)
+    render(<LinkChip link={ready(ITEM)} />)
+    await hoverChip(/ABC-2/)
+    expect(screen.queryByText(ITEM.summary!)).toBeNull()
+    expect(screen.getByRole('link', { name: /ABC-2/ }).getAttribute('href')).toBe('#item')
+  })
+})

package/src/LinkChip.tsx

@@ -0,0 +1,51 @@
+/**
+ * A link in running text: the icon (or the author's face, for words a person
+ * wrote), the key, the title cut short, the status as its shape. Loading
+ * keeps the icon, since the kind is known from the address; not available says
+ * so in words. Hovering it shows its card; a tap opens it.
+ */
+import { Avatar } from './Avatar'
+import { InlineChip } from './InlineChip'
+import type { LinkState } from './linked'
+import { chosenOf } from './linked'
+import { LinkedIcon, LinkKey, StatusMark } from './LinkParts'
+import { LinkPreview } from './LinkPreview'
+import { SkeletonBar } from './Skeleton'
+
+export interface LinkChipProps {
+  link: LinkState
+  /** Hovering shows its card. Off where a card would cover what the reader is choosing from. */
+  preview?: boolean
+}
+
+export function LinkChip({ link, preview = true }: LinkChipProps) {
+  if (link.state === 'loading') {
+    return (
+      <InlineChip icon={<LinkedIcon kind={link.kind} size={14} tone="inherit" />} aria-busy>
+        <SkeletonBar className="h-2.5 w-16" />
+      </InlineChip>
+    )
+  }
+  if (link.state === 'unavailable') {
+    return (
+      <InlineChip tone="muted" icon={<LinkedIcon kind={link.kind} size={14} tone="inherit" />}>
+        {link.noun}, not available
+      </InlineChip>
+    )
+  }
+  const { linked } = link
+  const status = chosenOf(linked.status)
+  const said = linked.kind === 'message' && linked.author
+  const chip = (
+    <InlineChip
+      icon={said ? <Avatar name={said.name} src={said.picture} size={16} /> : <LinkedIcon kind={linked.kind} size={14} tone="inherit" />}
+      href={linked.href}
+      className="max-w-[28ch]"
+    >
+      {linked.key && <LinkKey>{linked.key}</LinkKey>}
+      <span className="truncate">{said ? `${said.name}: ${linked.body ?? linked.title}` : linked.title}</span>
+      {status?.colour && <StatusMark status={{ label: status.label, colour: status.colour }} />}
+    </InlineChip>
+  )
+  return preview ? <LinkPreview linked={linked}>{chip}</LinkPreview> : chip
+}

package/src/LinkParts.mdx

@@ -0,0 +1,49 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as LinkPartsStories from './LinkParts.stories'
+
+<Meta of={LinkPartsStories} />
+
+# LinkParts
+
+The small parts the link widgets are built from: the pickers, the conversation count, a status's shape and a progress ring.
+
+<Canvas of={LinkPartsStories.Pickers} />
+
+## When
+
+- **LinkPickers** — a status and an owner, changed in place. A picker with no `onChange`, or `readOnly`, reads as words in the same place.
+- **CommentCount** — how much was said, as a link to where it is read; brighter, with a dot, when there is something unread for a member.
+- **StatusMark** — a status as its shape, which reads without colour; its words on hover.
+- **ProgressRing** — how far along, as a ring and a count.
+- **LinkedIcon**, **LinkKey** — the icon for what a link stands for, and its key.
+
+<Canvas of={LinkPartsStories.PickersReadOnly} />
+<Canvas of={LinkPartsStories.Conversation} />
+<Canvas of={LinkPartsStories.Marks} />
+
+## When not
+
+- A whole link → **LinkChip**, **LinkRow**, **LinkCard**.
+- A choice in a form → **Select**.
+
+## How
+
+```tsx
+import { LinkPickers, CommentCount } from '@estiva-app/ui'
+
+<LinkPickers status={{ value: statusKey, options: statuses, onChange: setStatus }} owner={{ value: ownerKey, options: people }} ownerLabel="Owner" />
+<CommentCount conversation={{ count: 4, href: conversationHref, unread: isMemberWithUnread }} />
+```
+
+- `unread` only for a member of the conversation: anyone else sees the count alone.
+
+## What it owns
+
+| It does | So you never write |
+|---|---|
+| Draws a value as words where it may not be changed | a disabled select |
+| Says the count and whether it is unread to a screen reader | an `aria-label` of your own |
+
+## Props
+
+<Controls of={LinkPartsStories.PickersReadOnly} />

package/src/LinkParts.stories.tsx

@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useState } from 'react'
+import { PEOPLE, STATUS_OPTIONS } from './linked.examples'
+import { CommentCount, LinkPickers, ProgressRing, StatusMark } from './LinkParts'
+
+const meta = {
+  title: 'Components/LinkParts',
+  component: LinkPickers,
+  parameters: { layout: 'padded' },
+} satisfies Meta<typeof LinkPickers>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** A status and an owner, changed from the card. */
+export const Pickers: Story = {
+  render: () => {
+    const [status, setStatus] = useState('todo')
+    const [owner, setOwner] = useState<string | undefined>(undefined)
+    return (
+      <LinkPickers
+        status={{ value: status, options: STATUS_OPTIONS, onChange: setStatus }}
+        owner={{ value: owner, options: PEOPLE, onChange: setOwner }}
+        ownerLabel="Owner"
+      />
+    )
+  },
+}
+
+/** To a reader who may not change them, and in the hover preview: the same values, as words. */
+export const PickersReadOnly: Story = {
+  args: { status: { value: 'doing', options: STATUS_OPTIONS }, owner: { value: 'b', options: PEOPLE } },
+}
+
+/** Nobody owns it yet, read only. */
+export const NoOwner: Story = {
+  args: { status: { value: 'todo', options: STATUS_OPTIONS }, owner: { value: undefined, options: PEOPLE } },
+}
+
+/** The count of what was said, opening where it is read. With something unread, to a member: brighter, with a dot. */
+export const Conversation: Story = {
+  render: () => (
+    <div className="flex items-center gap-4">
+      <CommentCount conversation={{ count: 4, href: '#conversation' }} />
+      <CommentCount conversation={{ count: 5, href: '#conversation', unread: true }} />
+    </div>
+  ),
+}
+
+/** A status as its shape, and progress as a ring. */
+export const Marks: Story = {
+  render: () => (
+    <div className="flex items-center gap-4">
+      {STATUS_OPTIONS.map((option) => (
+        <StatusMark key={option.value} status={{ label: option.label, colour: option.colour! }} />
+      ))}
+      <ProgressRing done={2} total={5} />
+      <ProgressRing done={5} total={5} />
+    </div>
+  ),
+}