@estiva-app/ui 0.24.1 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.24.1",
+  "version": "0.26.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",

package/registry.json

@@ -4,9 +4,9 @@
     "kind": "package",
     "repo": "estiva-ui",
     "package": "@estiva-app/ui",
-    "packageVersion": "0.24.1",
-    "exports": 84,
-    "typeExports": 94,
+    "packageVersion": "0.26.0",
+    "exports": 87,
+    "typeExports": 96,
     "files": null
   },
   "storybook": {
@@ -129,11 +129,35 @@
           "required": false,
           "note": "The picture an image card draws. Without it an image is drawn as a row."
         },
+        {
+          "name": "alt",
+          "takes": "text",
+          "required": false,
+          "note": "What the picture shows, where the sender said — Ship carries one on every `imeta`."
+        },
+        {
+          "name": "remoteSrc",
+          "takes": "text",
+          "required": false,
+          "note": "A file the app has to *fetch* before it can be used — one on a relay, where reading it needs the reader's own authorization (UIG-35)."
+        },
+        {
+          "name": "remoteFullSrc",
+          "takes": "text",
+          "required": false,
+          "note": "The full-size picture, fetched only when someone opens it."
+        },
+        {
+          "name": "fetchImage",
+          "takes": "a handler",
+          "required": false,
+          "note": "How this app fetches a picture it is allowed to read: a URL in, a URL the browser can draw out (an object URL, usually)."
+        },
         {
           "name": "onOpen",
           "takes": "a handler",
           "required": false,
-          "note": "What a click on an image's picture does — the app's full-screen view."
+          "note": "What a click on an image's picture does."
         },
         {
           "name": "onDownload",
@@ -141,6 +165,12 @@
           "required": false,
           "note": "Shows a download control on hover or focus, and calls this."
         },
+        {
+          "name": "download",
+          "takes": "true/false",
+          "required": false,
+          "note": "Shows the download control and saves the file itself, under `name`: the original where there is one (`remoteFullSrc`), otherwise what the card is drawing."
+        },
         {
           "name": "pending",
           "takes": "true/false",
@@ -1680,6 +1710,49 @@
       "docPage": null,
       "app": null
     },
+    {
+      "name": "ErrorBoundary",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/ErrorBoundary.tsx",
+      "purpose": "Keeps a crash inside what it holds: that part shows \"Something went wrong … Your data is safe — try again.\" with a Try again button, and the rest of the page keeps working.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "children",
+          "takes": "anything",
+          "required": true,
+          "note": null
+        },
+        {
+          "name": "label",
+          "takes": "text",
+          "required": false,
+          "note": "What it holds, said in the message and the console line: \"Something went wrong in the {label}.\""
+        },
+        {
+          "name": "fallbackClassName",
+          "takes": "text",
+          "required": false,
+          "note": "The room the message fills where no flex column holds it — the whole screen, for the app's own."
+        },
+        {
+          "name": "frame",
+          "takes": "a handler",
+          "required": false,
+          "note": "Draws the message inside a frame of yours, in the same place: `ListColumn` keeps its title this way."
+        }
+      ],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "feedback-errorboundary--docs",
+      "storyId": "feedback-errorboundary--in-a-panel",
+      "docPage": "src/ErrorBoundary.mdx",
+      "app": null
+    },
     {
       "name": "Field",
       "repo": "estiva-ui",
@@ -2327,6 +2400,66 @@
       "docPage": "src/Kbd.mdx",
       "app": null
     },
+    {
+      "name": "Lightbox",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/Lightbox.tsx",
+      "purpose": "A picture, full screen, on a scrim — what a thumbnail opens into.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "src",
+          "takes": "text",
+          "required": true,
+          "note": "The picture to show. Swapping it — a thumbnail for the original, once it arrives — swaps what is on screen, with no flash of nothing."
+        },
+        {
+          "name": "alt",
+          "takes": "text",
+          "required": true,
+          "note": "What the picture is. Names the viewer for assistive tech too."
+        },
+        {
+          "name": "onClose",
+          "takes": "a handler",
+          "required": true,
+          "note": null
+        },
+        {
+          "name": "className",
+          "takes": "text",
+          "required": false,
+          "note": "Extra classes on the picture itself."
+        }
+      ],
+      "variants": [],
+      "ownsBehaviours": [
+        {
+          "id": "portal",
+          "behaviour": "Floats on top of the page"
+        },
+        {
+          "id": "page-keys",
+          "behaviour": "Takes its keys by itself"
+        },
+        {
+          "id": "focus",
+          "behaviour": "Holds focus inside while open, and gives it back"
+        },
+        {
+          "id": "scroll-lock",
+          "behaviour": "Stops the page behind it scrolling"
+        }
+      ],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "overlays-lightbox--docs",
+      "storyId": "overlays-lightbox--a-picture",
+      "docPage": "src/Lightbox.mdx",
+      "app": null
+    },
     {
       "name": "Link",
       "repo": "estiva-ui",
@@ -2428,12 +2561,6 @@
           "required": false,
           "note": "A row between the header and the list that stays put while the list scrolls — a field that adds to the list."
         },
-        {
-          "name": "spacing",
-          "takes": "rows | sections",
-          "required": false,
-          "note": "The room between rows. `rows` (2px) for a list of one kind of row; `sections` (4px) for groups with labels and dividers of their own."
-        },
         {
           "name": "collapsed",
           "takes": "true/false",
@@ -2444,7 +2571,7 @@
           "name": "children",
           "takes": "anything",
           "required": true,
-          "note": "The rows."
+          "note": "The rows, 2px apart. Groups are headed by a `CollapsibleSection` or a `SectionHeader`."
         },
         {
           "name": "className",
@@ -2453,15 +2580,7 @@
           "note": "Placement only."
         }
       ],
-      "variants": [
-        {
-          "prop": "spacing",
-          "values": [
-            "rows",
-            "sections"
-          ]
-        }
-      ],
+      "variants": [],
       "ownsBehaviours": [],
       "status": "stable",
       "migrationStage": null,
@@ -2766,6 +2885,24 @@
       "docPage": null,
       "app": null
     },
+    {
+      "name": "MenuSeparator",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/Menu.tsx",
+      "purpose": "The line between two groups of a menu, with its own 4px above and below (UIG-14, Katerina 19 September).",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "overlays-menu--docs",
+      "storyId": "overlays-menu--items",
+      "docPage": null,
+      "app": null
+    },
     {
       "name": "MenuSub",
       "repo": "estiva-ui",

package/src/AttachmentCard.mdx

@@ -14,11 +14,14 @@ waiting to be sent.
 
 The file decides the shape:
 
-- **an image with a picture** (`src`) — a 180px thumbnail; `onOpen` is what a
-  click on the picture does.
+- **an image with a picture** (`src`) — a 180px thumbnail, which opens full
+  screen when it is pressed. `onOpen` replaces that with the app's own.
 - **anything else** — a 240px row: a type tile, the name, the type and size.
   `href` opens it in a new tab; without one the row is dimmed.
-- `onDownload` — a download control that fades in on hover or keyboard focus.
+- `download` — a download control that fades in on hover or keyboard focus, and
+  the card saves the file. `onDownload` instead when the app must do it itself.
+- `remoteSrc` + `fetchImage` — a picture the reader needs permission for. The
+  card waits and says so if it is refused; `state` says the same by hand.
 - `state="loading"` — an image on its way. `state="unreadable"` — it could not
   be read: said, with a dashed hairline, never left as a gap.
 - **`pending`** — waiting to be sent: a 200px row with a remove control on its
@@ -39,15 +42,30 @@ The file decides the shape:
 ```tsx
 import { AttachmentCard } from '@estiva-app/ui'
 
-// Posted: the app fetched the picture, and opens it full screen itself.
-<AttachmentCard name={name} size={bytes} contentType={type} src={pictureUrl} onOpen={openFullScreen} onDownload={save} />
+// Posted, with the picture already in hand.
+<AttachmentCard name={name} size={bytes} contentType={type} src={pictureUrl} download />
+
+// Posted, on a relay: the card fetches it with your app's authorization, opens
+// it full screen and saves it. The original is fetched only when it is opened.
+<AttachmentCard
+  name={name}
+  size={bytes}
+  contentType={type}
+  remoteSrc={thumbUrl ?? mediaUrl}
+  remoteFullSrc={mediaUrl}
+  fetchImage={blobObjectUrl}
+  download
+/>
 
 // Waiting to be sent.
 <AttachmentCard pending name={name} size={bytes} state={uploading ? 'uploading' : 'ready'} src={localPreview} onRemove={remove} />
 ```
 
-- The card fetches nothing. Reading a file may need the reader's own permission,
-  and only the app has it: pass the result — `src`, `href`, `state`.
+- **How to fetch is the app's, what to draw is the card's.** `fetchImage` takes
+  a URL and returns one the browser can draw — an object URL, usually. The
+  card owns the wait, the refusal and the swap; it knows nothing about relays,
+  tokens or which app it is in.
+- A picture already in hand needs none of that: pass `src`.
 - A click on the picture, the download control and the remove control each stop
   there, so they never also click the card or row the attachment sits in.
 - The name truncates. When it is cut off, the full name is on hover; a name
@@ -57,7 +75,10 @@ import { AttachmentCard } from '@estiva-app/ui'
   on Base UI's `Button` like InputChip's ✕ — not an `IconButton`, the 24px
   square that fills on hover.
 
-- **Planned:** a Lightbox that opens a picture full screen, in migration stage 7.
+- A press on the picture opens it full screen, in **Lightbox**, unless `onOpen`
+  says what else to do.
+
+<Canvas of={AttachmentCardStories.OpenItFullScreen} />
 
 ## What it owns
 
@@ -67,6 +88,9 @@ It does these by itself. Write none of them around it.
 |---|---|---|
 | Stops the clicks on its picture, its download and its remove control, so they never also click the card or row around it | `stopPropagation` |  |
 | Shows the full name on hover when the name is cut off | a tooltip of your own |  |
+| Opens the picture full screen, in Lightbox | a viewer of your own, a portal, a scrim |  |
+| Fetches a picture that needs permission, and draws the wait and the refusal | a loading hook of your own |  |
+| Saves the file under its name, the original rather than the thumbnail | a `<a download>` of your own |  |
 
 ## Props
 

package/src/AttachmentCard.stories.tsx

@@ -90,3 +90,57 @@ export const Failed: Story = { args: { ...Pending.args, state: 'failed', name: '
 
 /** Attached, with something the sender should know: a warning, not an error — nothing failed. The full words are on hover. */
 export const Warning: Story = { args: { ...Pending.args, state: 'warning', note: 'Not everyone can see this', noteHint: 'Only this app has a copy of this file.' } }
+
+/**
+ * **Press the picture.** Without an `onOpen` the card opens it itself, full
+ * screen, in the package's `Lightbox` — Escape, the ✕ or the scrim closes it
+ * (UIG-35). Peek had written that viewer by hand and Ship had none at all.
+ */
+export const OpenItFullScreen: Story = {
+  parameters: {
+    layout: 'fullscreen',
+    // The viewer portals over the page — iframe it so it does not cover the docs.
+    docs: { story: { inline: false, height: '420px' } },
+  },
+  args: { name: 'checkout-flow.png', size: 840_000, contentType: 'image/png', src: WIDE, href: undefined, onOpen: undefined },
+  render: (args) => (
+    <div className="p-4">
+      <AttachmentCard {...args} />
+    </div>
+  ),
+}
+
+/**
+ * **A picture the reader has to be allowed to see**, which is every file on the
+ * relay: `remoteSrc` is where it lives and `fetchImage` is how this app fetches
+ * one with the reader's own authorization. The card waits, then draws it.
+ *
+ * Here the fetch takes a second, so the wait is visible. The two apps had
+ * written this same wait, once each.
+ */
+export const FetchedWithPermission: Story = {
+  parameters: { controls: { disable: true } },
+  args: {
+    name: 'checkout-flow.png',
+    size: 840_000,
+    contentType: 'image/png',
+    src: undefined,
+    href: undefined,
+    remoteSrc: 'relay://checkout-flow.png',
+    fetchImage: () => new Promise<string>((resolve) => setTimeout(() => resolve(WIDE), 1000)),
+  },
+}
+
+/** The same request, refused — a channel this reader is not in. The card says so, and does not leave a gap. */
+export const CouldNotBeFetched: Story = {
+  parameters: { controls: { disable: true } },
+  args: {
+    name: 'checkout-flow.png',
+    size: 840_000,
+    contentType: 'image/png',
+    src: undefined,
+    href: undefined,
+    remoteSrc: 'relay://checkout-flow.png',
+    fetchImage: () => Promise.reject(new Error('relay_membership_required')),
+  },
+}

package/src/AttachmentCard.test.tsx

@@ -179,4 +179,119 @@ describe('AttachmentCard', () => {
     await userEvent.tab()
     expect(document.activeElement).toBe(remove)
   })
+
+  /* UIG-35: what the two apps were doing around the card, and it now does. */
+
+  it('a picture that needs permission: the card waits, then draws what the app fetched', async () => {
+    const fetchImage = vi.fn().mockResolvedValue('blob:the-picture')
+    render(<AttachmentCard name="shot.png" contentType="image/png" remoteSrc="relay://shot" fetchImage={fetchImage} />)
+
+    // While it is in flight the card is the loading card, not a gap.
+    expect(screen.getByRole('status', { name: 'Loading shot.png' })).toBeTruthy()
+
+    const picture = await screen.findByAltText('shot.png')
+    expect(picture.getAttribute('src')).toBe('blob:the-picture')
+    expect(fetchImage).toHaveBeenCalledWith('relay://shot')
+  })
+
+  it('a document that has to be fetched keeps its row, and opens once the bytes land', async () => {
+    const fetchImage = vi.fn().mockResolvedValue('blob:the-file')
+    const { container } = render(<AttachmentCard name="report.pdf" size={2_412_000} remoteSrc="relay://report" fetchImage={fetchImage} />)
+
+    // Not the picture's loading card: the row is already saying what the file is.
+    expect(screen.getByText('report.pdf')).toBeTruthy()
+    expect(screen.queryByRole('status')).toBeNull()
+    expect(classesOf(rootOf(container))).toContain('w-[240px]')
+    expect(screen.queryByRole('link')).toBeNull()
+
+    await vi.waitFor(() => expect(screen.getByRole('link').getAttribute('href')).toBe('blob:the-file'))
+  })
+
+  it("the sender's words about a picture are its alt text, and name it in the viewer", async () => {
+    render(<AttachmentCard name="shot.png" contentType="image/png" src="blob:thumb" alt="the failing dialog" />)
+    expect(screen.getByAltText('the failing dialog')).toBeTruthy()
+    // The file's name still sits under the thumbnail: the two say different things.
+    expect(screen.getByText('shot.png')).toBeTruthy()
+
+    await userEvent.click(screen.getByRole('button', { name: 'Preview shot.png' }))
+    expect(screen.getByRole('dialog', { name: 'the failing dialog' })).toBeTruthy()
+  })
+
+  it('a refused request is said, with the unreadable card', async () => {
+    render(
+      <AttachmentCard name="shot.png" contentType="image/png" remoteSrc="relay://shot" fetchImage={() => Promise.reject(new Error('relay_membership_required'))} />,
+    )
+    expect(await screen.findByText('Could not be loaded')).toBeTruthy()
+  })
+
+  it('a fetcher written inline does not re-fetch on every render', async () => {
+    const calls = { n: 0 }
+    // A new function identity on every render of the app around it, which is
+    // what an inline `fetchImage={…}` is. Only the URL may start a fetch.
+    const Harness = ({ tick }: { tick: number }) => (
+      <AttachmentCard
+        name="shot.png"
+        contentType="image/png"
+        remoteSrc="relay://shot"
+        data-tick={tick}
+        fetchImage={() => {
+          calls.n += 1
+          return Promise.resolve('blob:the-picture')
+        }}
+      />
+    )
+    const { rerender } = render(<Harness tick={1} />)
+    await screen.findByAltText('shot.png')
+    rerender(<Harness tick={2} />)
+    rerender(<Harness tick={3} />)
+    expect(calls.n).toBe(1)
+  })
+
+  it('pressing the picture opens it full screen, and Escape closes it', async () => {
+    render(<AttachmentCard name="shot.png" contentType="image/png" src="blob:thumb" />)
+    await userEvent.click(screen.getByRole('button', { name: 'Preview shot.png' }))
+
+    const viewer = screen.getByRole('dialog', { name: 'shot.png' })
+    expect(viewer).toBeTruthy()
+
+    await userEvent.keyboard('{Escape}')
+    expect(screen.queryByRole('dialog')).toBeNull()
+  })
+
+  it('an app that wants its own viewer still gets the click, and no viewer opens', async () => {
+    const onOpen = vi.fn()
+    render(<AttachmentCard name="shot.png" contentType="image/png" src="blob:thumb" onOpen={onOpen} />)
+    await userEvent.click(screen.getByRole('button', { name: 'Preview shot.png' }))
+    expect(onOpen).toHaveBeenCalledTimes(1)
+    expect(screen.queryByRole('dialog')).toBeNull()
+  })
+
+  it('opening a relay picture fetches the original, and shows the thumbnail until it lands', async () => {
+    let landOriginal: (src: string) => void = () => {}
+    const fetchImage = vi.fn((url: string) =>
+      url === 'relay://original' ? new Promise<string>((resolve) => (landOriginal = resolve)) : Promise.resolve('blob:thumb'),
+    )
+    render(
+      <AttachmentCard name="shot.png" contentType="image/png" remoteSrc="relay://thumb" remoteFullSrc="relay://original" fetchImage={fetchImage} />,
+    )
+    await screen.findByAltText('shot.png')
+    await userEvent.click(screen.getByRole('button', { name: 'Preview shot.png' }))
+
+    // The thumbnail stands in: a moment of a smaller picture beats a moment of an empty screen.
+    expect(screen.getByRole('dialog').querySelector('img')?.getAttribute('src')).toBe('blob:thumb')
+
+    landOriginal('blob:original')
+    await vi.waitFor(() => expect(screen.getByRole('dialog').querySelector('img')?.getAttribute('src')).toBe('blob:original'))
+  })
+
+  it('the download control saves the original, not the thumbnail on screen', async () => {
+    const fetchImage = vi.fn().mockResolvedValue('blob:the-picture')
+    render(
+      <AttachmentCard name="shot.png" contentType="image/png" remoteSrc="relay://thumb" remoteFullSrc="relay://original" fetchImage={fetchImage} download />,
+    )
+    await screen.findByAltText('shot.png')
+    fetchImage.mockClear()
+    await userEvent.click(screen.getByRole('button', { name: 'Download shot.png' }))
+    expect(fetchImage).toHaveBeenCalledWith('relay://original')
+  })
 })