Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,13 @@ still apply).
the Phosphor set already installed via `presetIcons`) on a `<span class="i-ph:..." aria-hidden="true" />`.
Exception: purely data-driven/generative vector graphics (e.g. `DisplayDonut`'s
progress ring) aren't icons and stay inline `<svg>`.
- Anything that teleports (a reka `*Portal`, a `<Teleport>`) must route its target
- Prefer the platform for overlays: a modal is a native `<dialog>` opened with
`showModal()` (`useNativeDialog` in `composables/dialog.ts`), and a tooltip is
a native `[popover]` placed by CSS anchor positioning (`bindTooltip` /
`vTooltip` in `composables/tooltip.ts`). Both render in the top layer *in
place*: no Teleport, no z-index layer, and they can't escape a shadow root.
Animate them in CSS (`@starting-style` + `allow-discrete`), not JS.
- Anything that still teleports (a reka `*Portal`, a `<Teleport>`) must route its target
through `usePortalTarget(() => props.to)` and expose the `to?: string | HTMLElement`
prop, so the content stays inside an enclosing shadow root. Add the component to
the `cases` list in `test/portal.test.ts` and to the `Utilities/ShadowRoot` story.
Expand Down
34 changes: 16 additions & 18 deletions packages/design/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,21 +28,15 @@ export default defineConfig({
],
// Required — most shipped styles recolor overlays with token `--at-apply`
// directives; this transformer expands them (and lets you reuse tokens in CSS).
// (vue-afloat.css is the exception — it themes via vue-afloat's own
// `--vue-afloat-*` CSS variables and needs no transformer.)
transformers: [transformerDirectives()],
// The preset ships no z-index scale (stacking is the app's to own) and blocks
// plain `z-<number>`. Define the named layers the overlay components use here —
// these values are yours; tune them to fit your app's stack.
// these values are yours; tune them to fit your app's stack. (Dialogs and
// tooltips need none: they open in the browser's top layer.)
shortcuts: {
'z-nav': 'z-[30]',
'z-dropdown': 'z-[40]',
'z-tooltip': 'z-[45]',
'z-toast': 'z-[50]',
'z-modal-backdrop': 'z-[60]',
'z-modal-content': 'z-[70]',
'z-drawer-backdrop': 'z-[80]',
'z-drawer-content': 'z-[90]',
},
})
```
Expand All @@ -56,7 +50,7 @@ export default defineConfig({
import ActionButton from '@antfu/design/components/Action/ActionButton.vue'
import DisplayBadge from '@antfu/design/components/Display/DisplayBadge.vue'
import OverlayModal from '@antfu/design/components/Overlay/OverlayModal.vue'
import '@antfu/design/styles.css' // everything, incl. splitpanes/reka/vue-afloat overrides
import '@antfu/design/styles.css' // everything, incl. splitpanes/reka overrides, dialogs and tooltips
```

`styles.css` bundles every overlay engine's override. If you don't use them all,
Expand All @@ -65,7 +59,8 @@ cherry-pick instead so unused (`splitpanes`/`reka-ui`) CSS never ships:
```ts
import '@antfu/design/styles/base.css'
import '@antfu/design/styles/scrollbar.css'
import '@antfu/design/styles/vue-afloat.css' // only if you use tooltips
import '@antfu/design/styles/dialog.css' // only if you use OverlayModal/Drawer/Confirm
import '@antfu/design/styles/tooltip.css' // only if you use tooltips
```

The package ships **raw `.ts` / `.vue` source** (no bundling) — your build
Expand All @@ -88,7 +83,7 @@ directives) plus, recommended, `@unocss/eslint-plugin` for the feedback loop.
| `./components/*` | one readable `.vue` per component (e.g. `./components/Display/DisplayBadge.vue`) |
| `./unocss` | the single `presetAnthonyDesign` preset |
| `./utils` | color, format, path, semver, contrast, keybinding helpers (pure, stateless) |
| `./composables/*` | Vue helpers: `colorScheme` (opt-in scheme context), `toast` (`useToast` queue), and `agent` (agent bridge) |
| `./composables/*` | Vue helpers: `colorScheme` (opt-in scheme context), `toast` (`useToast` queue), `dialog` (`useNativeDialog`), `tooltip` (`vTooltip`, `bindTooltip`), and `agent` (agent bridge) |
| `./a11y` | programmatic color-contrast scan |
| `./styles.css`, `./styles/*` | all styles, or per-concern files |
| `./splitpanes.d.ts` | opt-in fallback types for older `splitpanes` (v4.1.2+ ships its own) |
Expand Down Expand Up @@ -177,14 +172,17 @@ their own:
utilities on its child. `:host(.dark)` is not an alternative: these are
descendant selectors, and they can't reach across the boundary.
- **Global CSS can't pierce the boundary — inline the styles.** `@antfu/design/styles/*`
(scrollbar, reka-ui animations, vue-afloat, …) must be part of the sheet you
(scrollbar, reka-ui animations, dialog, tooltip, …) must be part of the sheet you
inject into the root, alongside the UnoCSS output. They're written with `*` /
unscoped selectors precisely so they work in either place. Add
`scrollbar-gutter: stable` on your own scroll container if you want the gutter
reserved.

Portaled content needs no setup. Every component that teleports — the dialogs
(`OverlayModal`, `OverlayDrawer`, `OverlayConfirm`), the poppers (`FormSelect`,
Overlays need no setup. The dialogs (`OverlayModal`, `OverlayDrawer`,
`OverlayConfirm`) are native `<dialog>`s and the tooltips (`OverlayTooltip`,
`v-tooltip`) are native popovers: both open in the browser's top layer *in
place*, so they never leave the shadow root. Every component that teleports
instead — the poppers (`FormSelect`,
`FormCombobox`, `OverlayDropdown`, `OverlayHoverCard`, `OverlayContextMenu`,
`LayoutMenubar`) and `FeedbackToasts` — detects the enclosing shadow root and
teleports into a container appended to it, which also mirrors the `dark`/`light`
Expand Down Expand Up @@ -267,14 +265,14 @@ tsx node_modules/@antfu/design/a11y/cli.ts http://localhost:6006/iframe.html

| Component | Use it for |
|---|---|
| `OverlayConfirm` | an AlertDialog for a confirm/cancel decision, `variant="danger"` for destructive actions. |
| `OverlayConfirm` | a native alert `<dialog>` for a confirm/cancel decision, `variant="danger"` for destructive actions. |
| `OverlayContextMenu` (+ `OverlayContextMenuItem`, `OverlayContextMenuLabel`, `OverlayContextMenuSeparator`) | a right-click menu. |
| `OverlayDrawer` | a slide-in panel from any `side` (left/right/top/bottom), sized by `width`. |
| `OverlayDrawer` | a slide-in native `<dialog>` panel from any `side` (left/right/top/bottom), sized by `width`. |
| `OverlayDropdown` (+ `OverlayDropdownCheckboxItem`, `OverlayDropdownGroup`, `OverlayDropdownLabel`, `OverlayDropdownRadioGroup`, `OverlayDropdownRadioItem`, `OverlayDropdownSeparator`, `OverlayDropdownSub`) | a trigger-anchored dropdown menu. |
| `OverlayDropdownItem` | a selectable dropdown row — `icon`, `variant="danger"`, trailing `shortcut` (rendered via `DisplayKbd`). |
| `OverlayHoverCard` | a hover-triggered popover with configurable `openDelay`/`closeDelay`. |
| `OverlayModal` | a centered dialog (`title`, `description`, `#trigger` slot). |
| `OverlayTooltip` | a vue-afloat tooltip — text `content` or the `#content` slot, configurable `placement`/`delay`/`triggers`, plus a virtual-anchor mode for canvas/graph overlays. |
| `OverlayModal` | a centered native `<dialog>` (`title`, `description`, `#trigger` slot). |
| `OverlayTooltip` | a native tooltip (Popover API + CSS anchor positioning) — text `content` or the `#content` slot, configurable `placement`/`delay`/`triggers`, plus a virtual-anchor mode for canvas/graph overlays. |

### Layout

Expand Down
4 changes: 2 additions & 2 deletions packages/design/components/Action/ActionIconButton.vue
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<!-- @description a round icon-only button with a `tooltip`, `active` state, `#badge`. Compose with VueUse's `useDark` for a dark toggle. -->
<script setup lang="ts">
import { computed } from 'vue'
import { vTooltip } from 'vue-afloat'
import { vTooltip } from '../../composables/tooltip'

const props = withDefaults(
defineProps<{
Expand All @@ -10,7 +10,7 @@ const props = withDefaults(
to?: string
href?: string
icon?: string
/** Tooltip text (vue-afloat). Requires `@antfu/design/styles/vue-afloat.css`. */
/** Tooltip text (native popover). Styled by `@antfu/design/styles/tooltip.css`. */
tooltip?: string
active?: boolean
disabled?: boolean
Expand Down
2 changes: 1 addition & 1 deletion packages/design/components/Display/DisplayDate.vue
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
import type { SeverityScale } from '../../utils/format'
import { useIntervalFn } from '@vueuse/core'
import { computed, ref, toRef, watch } from 'vue'
import { vTooltip } from 'vue-afloat'
import { vTooltip } from '../../composables/tooltip'
import { formatDateTime, formatTimeAgo, getAgeColor } from '../../utils/format'

const props = withDefaults(
Expand Down
2 changes: 1 addition & 1 deletion packages/design/components/Display/DisplayFilePath.vue
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<!-- @description truncates, dims directories, decodes `.pnpm`, icon, link. -->
<script setup lang="ts">
import { computed } from 'vue'
import { vTooltip } from 'vue-afloat'
import { vTooltip } from '../../composables/tooltip'
import { getFileIcon } from '../../utils/icon'
import { parseReadablePath } from '../../utils/path'

Expand Down
82 changes: 41 additions & 41 deletions packages/design/components/Overlay/OverlayConfirm.vue
Original file line number Diff line number Diff line change
@@ -1,61 +1,61 @@
<!-- @description an AlertDialog for a confirm/cancel decision, `variant="danger"` for destructive actions. -->
<!-- @description a native alert `<dialog>` for a confirm/cancel decision, `variant="danger"` for destructive actions. -->
<script setup lang="ts">
import { AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogOverlay, AlertDialogPortal, AlertDialogRoot, AlertDialogTitle, AlertDialogTrigger } from 'reka-ui'
import { usePortalTarget } from '../../composables/portalTarget'
import { useTemplateRef } from 'vue'
import { useNativeDialog } from '../../composables/dialog'

const props = withDefaults(
withDefaults(
defineProps<{
title?: string
description?: string
confirmLabel?: string
cancelLabel?: string
/** `danger` paints the confirm button red for destructive actions. */
variant?: 'default' | 'danger'
/** Teleport target for the portal; defaults to the enclosing shadow root, else `document.body`. */
to?: string | HTMLElement
}>(),
{ confirmLabel: 'Confirm', cancelLabel: 'Cancel', variant: 'default' },
)

const emit = defineEmits<{ confirm: [], cancel: [] }>()
const open = defineModel<boolean>('open')

const portalTo = usePortalTarget(() => props.to)
// An alert dialog asks for a decision: Esc cancels, a backdrop click doesn't.
const native = useNativeDialog(useTemplateRef('dialog'), open, { lightDismiss: false })
const { Trigger } = native
</script>

<template>
<AlertDialogRoot v-model:open="open">
<AlertDialogTrigger v-if="$slots.trigger" as-child>
<slot name="trigger" />
</AlertDialogTrigger>
<AlertDialogPortal :to="portalTo">
<AlertDialogOverlay class="bg-[#ddd]/40 inset-0 fixed z-modal-backdrop backdrop-blur-sm dark:bg-black/40" data-af-animate />
<!-- Centered by the wrapper, whose padding is also the minimum margin — see OverlayModal. -->
<div class="p-4 flex pointer-events-none items-center inset-0 justify-center fixed z-modal-content sm:p-6">
<AlertDialogContent
class="p-4 outline-none border border-base rounded-xl bg-base max-h-full max-w-sm w-full pointer-events-auto shadow-2xl overflow-auto"
data-af-modal
>
<AlertDialogTitle v-if="title" class="color-base font-medium">
{{ title }}
</AlertDialogTitle>
<AlertDialogDescription v-if="description" class="text-sm mt-1 op-fade">
{{ description }}
</AlertDialogDescription>
<div class="mt-4 flex gap-2 justify-end">
<AlertDialogCancel class="btn-action" @click="emit('cancel')">
{{ cancelLabel }}
</AlertDialogCancel>
<AlertDialogAction
class="btn-primary"
:class="variant === 'danger' ? 'bg-red-500! hover:bg-red-600!' : ''"
@click="emit('confirm')"
>
{{ confirmLabel }}
</AlertDialogAction>
</div>
</AlertDialogContent>
</div>
</AlertDialogPortal>
</AlertDialogRoot>
<Trigger v-if="$slots.trigger">
<slot name="trigger" />
</Trigger>
<dialog
:id="native.id"
ref="dialog"
role="alertdialog"
:closedby="native.closedby"
:aria-labelledby="title ? `${native.id}-title` : undefined"
:aria-describedby="description ? `${native.id}-description` : undefined"
class="color-base m-auto p-4 outline-none border border-base rounded-xl bg-base max-h-[calc(100dvh-2rem)] max-w-sm w-[calc(100%-2rem)] shadow-2xl overflow-auto sm:max-h-[calc(100dvh-3rem)]"
data-af-modal
>
<h2 v-if="title" :id="`${native.id}-title`" class="color-base font-medium">
{{ title }}
</h2>
<p v-if="description" :id="`${native.id}-description`" class="text-sm mt-1 op-fade">
{{ description }}
</p>
<div class="mt-4 flex gap-2 justify-end">
<!-- `autofocus`: open on the least destructive choice. -->
<button v-bind="native.closeProps()" class="btn-action" autofocus @click="emit('cancel')">
{{ cancelLabel }}
</button>
<button
v-bind="native.closeProps()"
class="btn-primary"
:class="variant === 'danger' ? 'bg-red-500! hover:bg-red-600!' : ''"
@click="emit('confirm')"
>
{{ confirmLabel }}
</button>
</div>
</dialog>
</template>
89 changes: 45 additions & 44 deletions packages/design/components/Overlay/OverlayDrawer.vue
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
<!-- @description a slide-in panel from any `side` (left/right/top/bottom), sized by `width`. -->
<!-- @description a slide-in native `<dialog>` panel from any `side` (left/right/top/bottom), sized by `width`. -->
<script setup lang="ts">
import { DialogClose, DialogContent, DialogDescription, DialogOverlay, DialogPortal, DialogRoot, DialogTitle, DialogTrigger } from 'reka-ui'
import { computed } from 'vue'
import { usePortalTarget } from '../../composables/portalTarget'
import { computed, useTemplateRef } from 'vue'
import { useNativeDialog } from '../../composables/dialog'

const props = withDefaults(
defineProps<{
Expand All @@ -15,21 +14,22 @@ const props = withDefaults(
* full viewport width.
*/
width?: string | number
/** Teleport target for the portal; defaults to the enclosing shadow root, else `document.body`. */
to?: string | HTMLElement
}>(),
{ side: 'right' },
)

const open = defineModel<boolean>('open')

const portalTo = usePortalTarget(() => props.to)
const native = useNativeDialog(useTemplateRef('dialog'), open)
const { Trigger } = native

// A modal `<dialog>` is `position: fixed; inset: 0; margin: auto` by default:
// pin it to one edge instead.
const SIDE_CLASS = {
right: 'right-0 top-0 h-full w-80 max-w-[90vw] border-l',
left: 'left-0 top-0 h-full w-80 max-w-[90vw] border-r',
top: 'top-0 inset-x-0 h-1/3 border-b',
bottom: 'bottom-0 inset-x-0 h-1/3 border-t',
right: 'inset-[0_0_0_auto] h-full max-h-none w-80 max-w-[90vw] [border-width:0_0_0_1px]',
left: 'inset-[0_auto_0_0] h-full max-h-none w-80 max-w-[90vw] [border-width:0_1px_0_0]',
top: 'inset-[0_0_auto_0] w-full max-w-none h-1/3 [border-width:0_0_1px_0]',
bottom: 'inset-[auto_0_0_0] w-full max-w-none h-1/3 [border-width:1px_0_0_0]',
} as const

// Inline style rather than a class so any CSS length works; it wins over `w-80`.
Expand All @@ -41,38 +41,39 @@ const style = computed(() => {
</script>

<template>
<DialogRoot v-model:open="open">
<DialogTrigger v-if="$slots.trigger" as-child>
<slot name="trigger" />
</DialogTrigger>
<DialogPortal :to="portalTo">
<DialogOverlay class="bg-[#ddd]/40 inset-0 fixed z-drawer-backdrop backdrop-blur-sm dark:bg-black/40" data-af-animate />
<DialogContent
class="outline-none border-base bg-base flex flex-col shadow-2xl fixed z-drawer-content"
:class="SIDE_CLASS[side]"
:style="style"
data-af-drawer
:data-side="side"
>
<header class="px-4 py-3 border-b border-base flex shrink-0 gap-4 items-center justify-between">
<DialogTitle v-if="title" class="color-base font-medium">
{{ title }}
</DialogTitle>
<DialogDescription v-if="$slots.description" class="sr-only">
<slot name="description" />
</DialogDescription>
<slot name="header" />
<DialogClose class="btn-icon shrink-0 h-7 w-7" aria-label="Close">
<span class="i-ph:x" aria-hidden="true" />
</DialogClose>
</header>
<div class="p-4 flex-1 overflow-auto">
<slot />
<Trigger v-if="$slots.trigger">
<slot name="trigger" />
</Trigger>
<dialog
:id="native.id"
ref="dialog"
:closedby="native.closedby"
:aria-labelledby="title ? `${native.id}-title` : undefined"
class="color-base m-0 p-0 outline-none border-base border-solid bg-base shadow-2xl"
:class="SIDE_CLASS[side]"
:style="style"
data-af-drawer
:data-side="side"
>
<div class="flex flex-col h-full">
<header class="px-4 py-3 border-b border-base flex shrink-0 gap-4 items-center justify-between">
<h2 v-if="title" :id="`${native.id}-title`" class="color-base font-medium">
{{ title }}
</h2>
<div v-if="$slots.description" class="sr-only">
<slot name="description" />
</div>
<footer v-if="$slots.footer" class="px-4 py-3 border-t border-base flex shrink-0 gap-2 items-center justify-end">
<slot name="footer" />
</footer>
</DialogContent>
</DialogPortal>
</DialogRoot>
<slot name="header" />
<button v-bind="native.closeProps()" class="btn-icon shrink-0 h-7 w-7" aria-label="Close">
<span class="i-ph:x" aria-hidden="true" />
</button>
</header>
<div class="p-4 flex-1 overflow-auto">
<slot />
</div>
<footer v-if="$slots.footer" class="px-4 py-3 border-t border-base flex shrink-0 gap-2 items-center justify-end">
<slot name="footer" />
</footer>
</div>
</dialog>
</template>
Loading
Loading