@estiva-app/ui 0.92.0 → 0.93.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.92.0",
3
+ "version": "0.93.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,7 +4,7 @@
4
4
  "kind": "package",
5
5
  "repo": "estiva-ui",
6
6
  "package": "@estiva-app/ui",
7
- "packageVersion": "0.92.0",
7
+ "packageVersion": "0.93.0",
8
8
  "exports": 210,
9
9
  "typeExports": 213,
10
10
  "files": null
@@ -869,6 +869,18 @@
869
869
  "required": false,
870
870
  "note": "Why the action cannot succeed right now."
871
871
  },
872
+ {
873
+ "name": "href",
874
+ "takes": "text",
875
+ "required": false,
876
+ "note": "A link that looks like a button: an anchor, so the address stays real for a modified click, a new tab or \"copy link address\", as `IconButton` and `Link` keep it."
877
+ },
878
+ {
879
+ "name": "external",
880
+ "takes": "true/false",
881
+ "required": false,
882
+ "note": "With `href`: another site, or another app."
883
+ },
872
884
  {
873
885
  "name": "children",
874
886
  "takes": "anything",
@@ -5878,7 +5890,7 @@
5878
5890
  },
5879
5891
  {
5880
5892
  "name": "action",
5881
- "takes": "SectionAction",
5893
+ "takes": "a handler",
5882
5894
  "required": false,
5883
5895
  "note": "One button beside the ⋮, shown with it: any 16px icon, its tooltip and its handler — a `SectionHeader` action's shape."
5884
5896
  },
package/src/Button.mdx CHANGED
@@ -28,7 +28,9 @@ The push-button for an action: a verb, clicked once — "Create", "Save",
28
28
 
29
29
  - An icon with no label → **IconButton**.
30
30
  - Going somewhere rather than doing something → **Link**; **Tabs** or
31
- **Breadcrumb** when it is a view or a trail.
31
+ **Breadcrumb** when it is a view or a trail. A way somewhere that must
32
+ stand as a button (the way out to another app) is this Button with
33
+ `href`, still a link.
32
34
  - Choosing a value → **Select**. Acting from a popover list → **MenuItem**.
33
35
  - A control the person may never be allowed to use is **absent, not
34
36
  disabled**. `disabled` is for *momentarily* unavailable — and it says why,
@@ -62,6 +64,26 @@ import { IconPlus } from '@tabler/icons-react'
62
64
  wrapper — what a caller gets is the `<button>`, and a `Menu.Trigger` or
63
65
  a `Dialog.Close` can be it.
64
66
 
67
+ - **A link that looks like a button**: give it `href`. It draws an `<a>`
68
+ with the same look, so a modified click, a new tab and "copy link
69
+ address" work. `external` opens another site or another app in a new
70
+ tab, with `noopener noreferrer`, as Link's does. A link cannot be
71
+ disabled: with `disabled` or `disabledReason` it is the button again,
72
+ and says why.
73
+
74
+ ```tsx
75
+ import { Button, WithTooltip } from '@estiva-app/ui'
76
+ import { IconExternalLink } from '@tabler/icons-react'
77
+
78
+ <WithTooltip label="Open in the app that owns it">
79
+ <Button href={url} external size="small" leadingIcon={<IconExternalLink stroke={1.5} className="size-3.5" />}>
80
+ Open
81
+ </Button>
82
+ </WithTooltip>
83
+ ```
84
+
85
+ <Canvas of={ButtonStories.OpensAnotherApp} />
86
+
65
87
  - `variant="resolve"` is `primary` in every theme but Signal, where it is
66
88
  outlined at rest and green when pointed at — the Resolve button. `IconButton`
67
89
  has the same look.
@@ -75,7 +97,7 @@ It does these by itself. Write none of them around it.
75
97
 
76
98
  | It does | So you never write | Refused when written by hand |
77
99
  |---|---|---|
78
- | Says what it is to assistive technology: a button | `role="button"` | ✓ |
100
+ | Says what it is to assistive technology: a button, or a link with `href` | `role="button"` | ✓ |
79
101
  | Is reachable with Tab, also when it is disabled with a reason | a `tabIndex` | ✓ |
80
102
  | Presses on Enter and Space, and does nothing while disabled | a key handler | |
81
103
  | Keeps its 32px (24px small) in a scrolling column | `shrink-0` | |
@@ -85,7 +107,7 @@ It does these by itself. Write none of them around it.
85
107
  | Key | Does |
86
108
  |---|---|
87
109
  | Tab | Onto the button, also when it is disabled with a reason; never when it is plain `disabled`. |
88
- | Space / Enter | The action. Nothing while disabled. |
110
+ | Space / Enter | The action. Nothing while disabled. With `href`, Enter follows the link, as on any link. |
89
111
 
90
112
  ## Props
91
113
 
@@ -1,5 +1,5 @@
1
1
  import type { Meta, StoryObj } from '@storybook/react-vite'
2
- import { IconPlus } from '@tabler/icons-react'
2
+ import { IconExternalLink, IconPlus } from '@tabler/icons-react'
3
3
  import { Button } from './Button'
4
4
 
5
5
  const meta = {
@@ -86,3 +86,17 @@ export const AllVariants: Story = {
86
86
 
87
87
  /** `resolve`: primary, and in Signal outlined at rest and green when pointed at — Resolve. */
88
88
  export const Resolve: Story = { args: { variant: 'resolve', children: 'Resolve' } }
89
+
90
+ /** With `href` it is a link that looks like a button: Ctrl-click, a new tab and "copy link address" work as on any link. */
91
+ export const AsALink: Story = { args: { href: '#', children: 'Go to the list' } }
92
+
93
+ /**
94
+ * `external`: another site or another app, in a new tab. The small quiet button with the external-link icon is the
95
+ * way out to the app that owns a file; its tooltip names that app.
96
+ */
97
+ export const OpensAnotherApp: Story = {
98
+ args: { href: 'https://example.com', external: true, size: 'small', leadingIcon: <IconExternalLink stroke={1.5} className="size-3.5" />, children: 'Open' },
99
+ }
100
+
101
+ /** A link cannot be disabled: with `disabledReason` (or `disabled`) it draws as the button, and says why. */
102
+ export const ALinkWithAReason: Story = { args: { href: 'https://example.com', external: true, disabledReason: 'Sign in to open it', children: 'Open' } }
@@ -135,4 +135,37 @@ describe('Button', () => {
135
135
  expect(button.getAttribute('data-x')).toBe('y')
136
136
  expect(button.classList.contains('mt-2')).toBe(true)
137
137
  })
138
+
139
+ it('with an address it is a link a person can follow; another app opens in a new tab', () => {
140
+ render(
141
+ <>
142
+ <Button href="/list">Go to the list</Button>
143
+ <Button href="https://example.com/file" external size="small">
144
+ Open
145
+ </Button>
146
+ </>,
147
+ )
148
+ const inPlace = screen.getByRole('link', { name: 'Go to the list' })
149
+ expect(inPlace.getAttribute('href')).toBe('/list')
150
+ expect(inPlace.hasAttribute('target')).toBe(false)
151
+ const out = screen.getByRole('link', { name: 'Open' })
152
+ expect(out.getAttribute('href')).toBe('https://example.com/file')
153
+ expect(out.getAttribute('target')).toBe('_blank')
154
+ expect(out.getAttribute('rel')).toBe('noopener noreferrer')
155
+ expect(screen.queryByRole('button')).toBeNull()
156
+ })
157
+
158
+ it('a link that cannot be followed right now is the button, saying why', async () => {
159
+ const user = userEvent.setup()
160
+ render(
161
+ <Button href="https://example.com/file" external disabledReason="Sign in to open it">
162
+ Open
163
+ </Button>,
164
+ )
165
+ expect(screen.queryByRole('link')).toBeNull()
166
+ const button = screen.getByRole('button', { name: 'Open' })
167
+ expect(button.getAttribute('aria-disabled')).toBe('true')
168
+ await user.hover(button)
169
+ expect((await screen.findByRole('tooltip')).textContent).toBe('Sign in to open it')
170
+ })
138
171
  })
package/src/Button.tsx CHANGED
@@ -1,5 +1,6 @@
1
1
  import type { ComponentPropsWithRef, ReactNode } from 'react'
2
2
  import { Button as BaseButton } from '@base-ui/react/button'
3
+ import { useInAppClick } from './AppProvider'
3
4
  import { cn } from './cn'
4
5
  import { useFormBusy } from './formBusy'
5
6
  import { TooltipTrigger } from './Tooltip'
@@ -56,6 +57,16 @@ export interface ButtonProps extends ComponentPropsWithRef<'button'> {
56
57
  /** Why the action cannot succeed right now. Disables the button, keeps it
57
58
  * reachable by keyboard, and shows the reason as a tooltip on hover. */
58
59
  disabledReason?: string
60
+ /**
61
+ * A link that looks like a button: an anchor, so the address stays real for a
62
+ * modified click, a new tab or "copy link address", as `IconButton` and `Link`
63
+ * keep it. A router app's `navigate` (AppProvider) moves in place. A link
64
+ * cannot be disabled, so while it would be (`disabled`, `disabledReason`, a
65
+ * busy Form) it is the button (Katerina, 30 October).
66
+ */
67
+ href?: string
68
+ /** With `href`: another site, or another app. Opens in a new tab, with `noopener noreferrer`, as `Link`'s does. */
69
+ external?: boolean
59
70
  children: ReactNode
60
71
  }
61
72
 
@@ -68,59 +79,64 @@ export function Button({
68
79
  disabled,
69
80
  disabledReason,
70
81
  type = 'button',
82
+ href,
83
+ external = false,
71
84
  ...props
72
85
  }: ButtonProps) {
73
86
  const hasLeadingIcon = !!leadingIcon
74
87
  // Inside a busy Form: switched off, and looking it (formBusy.ts).
75
88
  const formBusy = useFormBusy()
76
- const button = (
77
- <BaseButton
78
- type={type}
79
- disabled={disabled || !!disabledReason || formBusy}
80
- focusableWhenDisabled={!!disabledReason}
81
- className={(state) =>
82
- cn(
83
- // No `self-center` here, deliberately — `IconButton` needs it and this
84
- // does not, and the difference is the `h-8` / `h-6` on the next two
85
- // lines. `align-items: stretch` only stretches a child whose cross
86
- // size is `auto`; a Button always states its height, so a stretching
87
- // parent cannot change it. Measured in Chrome on 2026-09-12, in the
88
- // 260px row of Finding 49: 32px with `self-center` and 32px without.
89
- // What the class DID do was override the caller on the other axis —
90
- // in a column it beats the parent's `items-start`, which centred the
91
- // four actions in Ship's `ProjectRail` and the trigger in five of
92
- // this package's own story frames, each of which asks for the top.
93
- // A control does not get to decide where its caller puts it.
94
- 'inline-flex items-center justify-center gap-1 rounded-md transition-colors font-sans font-medium',
95
- size === 'default' && 'h-8 min-h-8 text-btn-default',
96
- size === 'small' && 'h-6 min-h-6 text-btn-small',
97
- // Extra right padding beside a leading icon, for optical balance.
98
- size === 'default' && (hasLeadingIcon ? 'pl-2 pr-3' : 'px-2'),
99
- size === 'small' && (hasLeadingIcon ? 'pl-1.5 pr-2' : 'px-1.5'),
100
- !state.disabled && (variant === 'primary' || variant === 'resolve') && 'bg-accent-primary hover:bg-accent-hover text-text-inverse cursor-pointer signal:font-semibold',
101
- // @estiva-escape(no-copied-look): W2 (Katerina, 24 September: leave alone): an outlined button shares four words with Reaction's pill by coincidence
102
- !state.disabled && variant === 'outlined' && 'border border-border-default hover:bg-bg-hover text-text-primary cursor-pointer',
103
- !state.disabled && variant === 'muted' && 'hover:bg-bg-hover text-text-primary cursor-pointer',
104
- !state.disabled && variant === 'destructive' && 'hover:bg-error-muted text-error-default cursor-pointer',
105
- state.disabled && 'bg-bg-disabled text-text-disabled',
106
- // `pointer-events-none` only where the button is truly out of reach.
107
- // With a `disabledReason` the button IS the tooltip's trigger, and a
108
- // trigger the pointer cannot land on never opens one — Base UI already
109
- // swallows the click (`focusableWhenDisabled` gives `aria-disabled`
110
- // and a prevented `onClick`), so nothing else needs it.
111
- state.disabled && !disabledReason && 'pointer-events-none',
112
- state.disabled && variant === 'outlined' && 'border border-border-default',
113
- // Disabled too, as it always drew.
114
- variant === 'resolve' &&
115
- 'signal:bg-transparent signal:border signal:border-border-default signal:text-text-primary signal:shadow-none signal:hover:bg-success-muted signal:hover:border-success-outline signal:hover:text-success-default signal:transition-colors',
116
- className,
117
- )
118
- }
119
- {...props}
120
- >
121
- {leadingIcon}
122
- {children}
123
- </BaseButton>
124
- )
89
+ const unusable = disabled || !!disabledReason || formBusy
90
+ const anchor = props as unknown as ComponentPropsWithRef<'a'>
91
+ const inApp = useInAppClick(href, anchor.onClick)
92
+ const look = (off: boolean) =>
93
+ cn(
94
+ // No `self-center` here, deliberately — `IconButton` needs it and this
95
+ // does not, and the difference is the `h-8` / `h-6` on the next two
96
+ // lines. `align-items: stretch` only stretches a child whose cross
97
+ // size is `auto`; a Button always states its height, so a stretching
98
+ // parent cannot change it. Measured in Chrome on 2026-09-12, in the
99
+ // 260px row of Finding 49: 32px with `self-center` and 32px without.
100
+ // What the class DID do was override the caller on the other axis —
101
+ // in a column it beats the parent's `items-start`, which centred the
102
+ // four actions in Ship's `ProjectRail` and the trigger in five of
103
+ // this package's own story frames, each of which asks for the top.
104
+ // A control does not get to decide where its caller puts it.
105
+ 'inline-flex items-center justify-center gap-1 rounded-md transition-colors font-sans font-medium',
106
+ size === 'default' && 'h-8 min-h-8 text-btn-default',
107
+ size === 'small' && 'h-6 min-h-6 text-btn-small',
108
+ // Extra right padding beside a leading icon, for optical balance.
109
+ size === 'default' && (hasLeadingIcon ? 'pl-2 pr-3' : 'px-2'),
110
+ size === 'small' && (hasLeadingIcon ? 'pl-1.5 pr-2' : 'px-1.5'),
111
+ !off && (variant === 'primary' || variant === 'resolve') && 'bg-accent-primary hover:bg-accent-hover text-text-inverse cursor-pointer signal:font-semibold',
112
+ // @estiva-escape(no-copied-look): W2 (Katerina, 24 September: leave alone): an outlined button shares four words with Reaction's pill by coincidence
113
+ !off && variant === 'outlined' && 'border border-border-default hover:bg-bg-hover text-text-primary cursor-pointer',
114
+ !off && variant === 'muted' && 'hover:bg-bg-hover text-text-primary cursor-pointer',
115
+ !off && variant === 'destructive' && 'hover:bg-error-muted text-error-default cursor-pointer',
116
+ off && 'bg-bg-disabled text-text-disabled',
117
+ // `pointer-events-none` only where the button is truly out of reach.
118
+ // With a `disabledReason` the button IS the tooltip's trigger, and a
119
+ // trigger the pointer cannot land on never opens one — Base UI already
120
+ // swallows the click (`focusableWhenDisabled` gives `aria-disabled`
121
+ // and a prevented `onClick`), so nothing else needs it.
122
+ off && !disabledReason && 'pointer-events-none',
123
+ off && variant === 'outlined' && 'border border-border-default',
124
+ // Disabled too, as it always drew.
125
+ variant === 'resolve' &&
126
+ 'signal:bg-transparent signal:border signal:border-border-default signal:text-text-primary signal:shadow-none signal:hover:bg-success-muted signal:hover:border-success-outline signal:hover:text-success-default signal:transition-colors',
127
+ className,
128
+ )
129
+ const button =
130
+ href && !unusable ? (
131
+ <a href={href} {...(external ? { target: '_blank', rel: 'noopener noreferrer' } : {})} className={look(false)} {...anchor} onClick={inApp}>
132
+ {leadingIcon}
133
+ {children}
134
+ </a>
135
+ ) : (
136
+ <BaseButton type={type} disabled={unusable} focusableWhenDisabled={!!disabledReason} className={(state) => look(state.disabled)} {...props}>
137
+ {leadingIcon}
138
+ {children}
139
+ </BaseButton>
140
+ )
125
141
  return disabledReason ? <TooltipTrigger label={disabledReason}>{button}</TooltipTrigger> : button
126
142
  }
package/src/NavItem.tsx CHANGED
@@ -69,7 +69,7 @@ export interface NavItemProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href'
69
69
  /** The ⋮'s accessible name and tooltip. Default "More options for {label}". */
70
70
  menuLabel?: string
71
71
  /** One button beside the ⋮, shown with it: any 16px icon, its tooltip and its handler — a `SectionHeader` action's shape. With a menu too, it sits before the ⋮. */
72
- action?: SectionAction
72
+ action?: SectionAction & { onClick: () => void }
73
73
  /** Shown only while the row is pointed at or focused, left of the count: a neutral `Chip`, typically. */
74
74
  hint?: ReactNode
75
75
  /** A sentence about the item, in the package's tooltip while the label is pointed at; the row stays one line. Absent or blank, no tooltip. */
@@ -25,6 +25,8 @@ title the toggle — that is where a section folds.
25
25
 
26
26
  <Canvas of={SectionHeaderStories.PersistentActions} />
27
27
 
28
+ - An action with `menu` in place of `onClick` opens those items: a Sort or a
29
+ filter, where the choice is the action. The row stays lit while it is open.
28
30
  - `menu` gives the section a "More options" ⋮ after its actions, with what
29
31
  acts on the whole section — a folder's Rename, Archive. It is **NavItem**'s
30
32
  ⋮, revealed with the actions, and stays while its menu is open.
@@ -35,12 +35,18 @@ import { SectionLabel } from './SectionLabel'
35
35
  * old shape yet: the two hard-wired action slots (add, sort) became
36
36
  * `actions` — the caller brings the icon, the tooltip and the handler.
37
37
  */
38
- export interface SectionAction {
38
+ export type SectionAction = {
39
39
  /** 16px, stroke 1.5. */
40
40
  icon: ReactNode
41
41
  tooltip: string
42
- onClick: () => void
43
- }
42
+ } & (
43
+ | { onClick: () => void; menu?: undefined }
44
+ /**
45
+ * The button opens a menu of these items instead: a choice that is the
46
+ * action, a sort or a filter (Katerina, 30 October: Open work's Sort).
47
+ */
48
+ | { menu: ReactNode; onClick?: undefined }
49
+ )
44
50
 
45
51
  export interface SectionHeaderProps {
46
52
  title: string
@@ -225,11 +231,27 @@ export function SectionHeader({ title, chevron = false, icon, isExpanded = true,
225
231
  className="-mr-1 flex shrink-0 items-center"
226
232
  >
227
233
  <div className={cn('flex items-center gap-1', reveal)}>
228
- {actions?.map((action) => (
229
- <IconButton key={action.tooltip} tooltip={action.tooltip} aria-label={action.tooltip} onClick={action.onClick}>
230
- {action.icon}
231
- </IconButton>
232
- ))}
234
+ {actions?.map((action) =>
235
+ action.menu != null ? (
236
+ // `data-section-menu`, as the ⋮ has: the row stays lit while its menu is open.
237
+ <div key={action.tooltip} data-section-menu className="flex items-center">
238
+ <Menu
239
+ align="right"
240
+ trigger={
241
+ <IconButton tooltip={action.tooltip} aria-label={action.tooltip}>
242
+ {action.icon}
243
+ </IconButton>
244
+ }
245
+ >
246
+ {action.menu}
247
+ </Menu>
248
+ </div>
249
+ ) : (
250
+ <IconButton key={action.tooltip} tooltip={action.tooltip} aria-label={action.tooltip} onClick={action.onClick}>
251
+ {action.icon}
252
+ </IconButton>
253
+ ),
254
+ )}
233
255
  {menu != null && (
234
256
  <div data-section-menu className="flex items-center">
235
257
  <Menu
package/src/Toast.mdx CHANGED
@@ -57,6 +57,9 @@ showToast({ label: 'Link copied', type: 'success' })
57
57
  - **The action closes its own toast.** Pressing it runs `onAction`, if you
58
58
  gave one, then closes that toast and no other. A Dismiss is just
59
59
  `actionLabel: 'Dismiss'`.
60
+ - `onClose` is told once when the toast closes, however it closes. An Undo
61
+ that is a wait — the write held until the toast goes — writes there, so the
62
+ toast's own timer, which pauses while it is pointed at, is the only one.
60
63
  - `showToast` returns the toast's id. `dismissToast(id)` closes that toast;
61
64
  `dismissToast()` with no id closes **every** toast on screen.
62
65
  - A toast can be swiped away towards its corner — left or down.
package/src/Toast.tsx CHANGED
@@ -133,6 +133,12 @@ export interface ToastOptions {
133
133
  leadingIcon?: boolean
134
134
  /** Auto-dismiss after this many ms. Defaults to 5000. Pass 0 to disable. */
135
135
  durationMs?: number
136
+ /**
137
+ * Told once when the toast closes, however it closes: its own timer, its
138
+ * action, a swipe, Escape or `dismissToast`. For an action whose Undo is a
139
+ * wait — the write happens here, unless the Undo was pressed first.
140
+ */
141
+ onClose?: () => void
136
142
  }
137
143
 
138
144
  interface ToastValue {
@@ -163,11 +169,12 @@ export function ToastProvider({ children }: { children: ReactNode }) {
163
169
  const manager = useMemo(() => BaseToast.createToastManager<ToastData>(), [])
164
170
  const value = useMemo<ToastValue>(
165
171
  () => ({
166
- showToast: ({ label, type = 'neutral', leadingIcon = true, actionLabel, onAction, durationMs = 5000 }) =>
172
+ showToast: ({ label, type = 'neutral', leadingIcon = true, actionLabel, onAction, durationMs = 5000, onClose }) =>
167
173
  manager.add({
168
174
  title: label,
169
175
  type,
170
176
  timeout: durationMs,
177
+ onClose,
171
178
  // A failure interrupts; everything else waits for a pause.
172
179
  priority: type === 'error' ? 'high' : 'low',
173
180
  data: { leadingIcon, actionLabel, onAction },