@ui-sdk/vue 0.0.0-stage → 0.1.0-beta.1

package/docs/parts-and-composition.md

@@ -0,0 +1,85 @@
+# Parts and Composition
+
+Put a component's parts together and choose what each one renders.
+
+A component can have several parts. A Popover has a root to hold its state, a trigger to open it, and content to show.
+
+## Put Parts Together
+
+Import the parts you need and nest them as shown in the component's Composition:
+
+```vue
+<script setup lang="ts">
+import {
+  Popover,
+  PopoverClose,
+  PopoverContent,
+  PopoverTitle,
+  PopoverTrigger,
+} from "@ui-sdk/vue/popover"
+</script>
+
+<template>
+  <Popover>
+    <PopoverTrigger>Details</PopoverTrigger>
+    <PopoverContent>
+      <PopoverTitle>Project Details</PopoverTitle>
+      <p>Last updated today.</p>
+      <PopoverClose>Done</PopoverClose>
+    </PopoverContent>
+  </Popover>
+</template>
+```
+
+`Popover` shares state without adding an element. Other roots, such as `Tabs`, do render an element. Parts find their root through the framework's context, so you can put your own components between them.
+
+## Choose the Element
+
+Render a menu item as a link:
+
+```vue
+<script setup lang="ts">
+import { Menu, MenuContent, MenuItem, MenuTrigger } from "@ui-sdk/vue/menu"
+</script>
+
+<template>
+  <Menu>
+    <MenuTrigger>Account</MenuTrigger>
+    <MenuContent>
+      <MenuItem href="/settings">
+        <template #render="{ props }">
+          <a v-bind="props">Settings</a>
+        </template>
+      </MenuItem>
+    </MenuContent>
+  </Menu>
+</template>
+```
+
+The `#render` slot receives the part's `props` and `state`. Bind the props with `v-bind="props"` to keep the part's behavior connected. It also receives `children`, the part's own content, like a slider thumb's range input: render it inside your element with `<component :is="children" />`. A component works too: the part binds to its root element, so give the component one element at its root.
+
+Your event handler runs first. Calling `event.preventDefault()` skips the built-in handler. Keep the supplied roles, IDs, and ARIA state when rendering your own element. A name or typing hint you pass replaces the part's own: `aria-label`, `aria-labelledby`, `aria-description`, `title`, `autocomplete`, `autocapitalize`, `autocorrect`, `inputmode` and `spellcheck`. Roles, `tabindex`, references like `aria-controls` and `aria-describedby`, state attributes and `data-slot` stay the part's, since its behavior reads them.
+
+## Read the State
+
+The part can pass its state to its content:
+
+```vue
+<script setup lang="ts">
+import { Toggle } from "@ui-sdk/vue/toggle"
+</script>
+
+<template>
+  <Toggle v-slot="{ state }" aria-label="Mute">{{
+    state.pressed ? "Mute on" : "Mute off"
+  }}</Toggle>
+</template>
+```
+
+Keep the accessible name stable when the content changes. Here, `aria-label="Mute"` names the toggle and `aria-pressed` reports its state.
+
+## Name the Control
+
+Use the component's label or title part, such as `FieldLabel` or `DialogTitle`. Give controls without visible text an `aria-label`.
+
+[Custom Parts](./custom-parts.md) covers writing a part with logic of its own.

package/docs/popups.md

@@ -0,0 +1,108 @@
+# Popups
+
+Place popup content, control dismissal, and choose when it stays mounted.
+
+Popovers, menus, selects, and dialogs use the browser's top layer. They render in place, above the page, so you don't need a portal or Positioner part. Their events bubble through the elements around them like any other child's, so a click handler or a link wrapped around a popup also gets the clicks inside it. Keep popups outside clickable cards and links.
+
+## Place the Content
+
+Set placement on the content part:
+
+```vue
+<script setup lang="ts">
+import {
+  Popover,
+  PopoverClose,
+  PopoverContent,
+  PopoverTitle,
+  PopoverTrigger,
+} from "@ui-sdk/vue/popover"
+</script>
+
+<template>
+  <Popover>
+    <PopoverTrigger>Details</PopoverTrigger>
+    <PopoverContent side="bottom" align="start" :side-offset="8">
+      <PopoverTitle>Project Details</PopoverTitle>
+      <p>Last updated today.</p>
+      <PopoverClose>Done</PopoverClose>
+    </PopoverContent>
+  </Popover>
+</template>
+```
+
+The popup flips or shifts when there isn't enough room.
+
+| Prop                | What It Does                                                                                         |
+| ------------------- | ---------------------------------------------------------------------------------------------------- |
+| `side`              | Chooses `top`, `bottom`, `left`, `right`, `start`, or `end`. Start and end follow reading direction. |
+| `align`             | Aligns the popup to the start, center, or end of that side.                                          |
+| `side-offset`       | Sets the gap from the anchor, in pixels.                                                             |
+| `align-offset`      | Shifts it along its side.                                                                            |
+| `collision-padding` | Leaves space from the window's edges.                                                                |
+
+An `anchor` positions the popup against another element. The component's page lists the anchors it accepts.
+
+## Control Dismissal
+
+Set `dismissible` to false to stop Escape, outside presses, focus leaving, Back, and sheet swipes from closing it. The trigger, Close part, and controller can still close it:
+
+```vue
+<script setup lang="ts">
+import {
+  Popover,
+  PopoverClose,
+  PopoverContent,
+  PopoverTitle,
+  PopoverTrigger,
+} from "@ui-sdk/vue/popover"
+</script>
+
+<template>
+  <Popover :dismissible="false">
+    <PopoverTrigger>Details</PopoverTrigger>
+    <PopoverContent>
+      <PopoverTitle>Project Details</PopoverTitle>
+      <p>Last updated today.</p>
+      <PopoverClose>Done</PopoverClose>
+    </PopoverContent>
+  </Popover>
+</template>
+```
+
+Use `@dismiss-attempt` to hear each refused dismissal. [State and Events](./state-and-events.md) shows how to cancel just one reason.
+
+## Modals and Sheets
+
+`modal` set to true makes the rest of the page inert and locks scrolling. Each component documents its default.
+
+Menu, Select, Combobox, Autocomplete, Popover, and Dialog support `presentation="auto"` to become a sheet on small touch screens. Use `presentation="sheet"` to always show a sheet.
+
+## Focus
+
+Dialogs, alert dialogs, drawers, and popovers move focus into their content when they open. Where it lands depends on how they opened:
+
+| Opened With                                  | Focus Goes To                                                |
+| -------------------------------------------- | ------------------------------------------------------------ |
+| Keyboard, screen reader, mouse, pen, or code | The element `initial-focus` picks.                           |
+| Touch                                        | The content itself, so no on-screen keyboard appears.        |
+| Hover                                        | Nowhere. Focus stays where it is.                            |
+| Rendered open                                | Nowhere, except in a dialog, which takes focus as it mounts. |
+
+`initial-focus` defaults to `"auto"`: the first focusable element, or the content when it has none. A dialog tries an element with `autofocus` first, and an alert dialog tries its first Close part. Pass `"content"` to focus the content itself, `"none"` to leave focus alone, or a CSS selector, an element, or a function that returns one.
+
+`modal` decides whether Tab can leave. With `true` or `"trap-focus"`, Tab and Shift+Tab wrap inside the content. With `false`, Tab moves from the trigger into a popover and on to the page after it, and focus leaving closes the popover. A non-modal dialog stays open.
+
+When a popup closes while focus is inside it, focus returns to the trigger. If the trigger is gone or can't take focus, focus goes to the element focused before the popup opened, then where the popup it was opened from would return focus, then to the nearest focusable element after where the trigger was. A popup a controller opened returns to the element focused before it first. Set `final-focus` to `"none"` to leave focus alone, or to a selector, an element, or a function to send it somewhere else. Closing because focus moved away never moves it back, and neither does pressing something focusable outside a non-modal popup.
+
+Menus, selects, and comboboxes handle focus within their own lists, and tooltips never move it. Each component's page covers its own.
+
+## Mounting and Containers
+
+Closed content unmounts after its exit animation. `keep-mounted` leaves it in the page, hidden. `@open-change-complete` runs when opening or closing finishes, including animations.
+
+Use `container` to render into another element, a shadow root, or an element in an iframe. Focus, Escape, and scroll locking then work in the document and shadow root the content renders in. Keep a dialog containing a form outside any surrounding form, or move its content with `container`, to avoid nested forms.
+
+In a page `<KeepAlive>` caches, an open popup leaves with the page, from its `container` too, and comes back open when the page does, with focus in it if it's modal.
+
+[Styling and Animation](./styling-and-animation.md) covers transitions. For toasts and confirms, mount `OverlayHost` once near your app's root; [Toast](./components/toast.md) and [Alert Dialog](./components/alert-dialog.md) show the setup.

package/docs/rendering.md

@@ -0,0 +1,56 @@
+# Rendering Primitives
+
+Turn a Core primitive into Vue components with createParts.
+
+This page renders the rating from [Compose Behaviors](./core.md#compose-behaviors). Start with that guide's [complete `rating.ts`](./core.md#complete-primitive): it already handles selection, arrow keys, and focus. Here we'll connect its `root` and `star` slots to Vue.
+
+## Create the Parts
+
+`createParts` maps slots to elements. Save this beside `rating.ts`:
+
+```ts title="rating-parts.ts"
+import { createParts } from "@ui-sdk/vue/primitive"
+import { rating } from "./rating"
+
+const { Root: RatingRoot, Star: RatingStar } = createParts(rating, {
+  root: "div",
+  star: "button",
+})
+
+export { RatingRoot, RatingStar }
+```
+
+`Root` creates the instance and shares it with the parts inside. Each mapped slot becomes a component. Slot names become Pascal case: `star` becomes `Star`, and `tab-icon` would become `TabIcon`.
+
+If you leave out the `root` tag, `Root` still shares the instance but renders only its children.
+
+## Render the Rating
+
+The root accepts the primitive's options and the element's props. Each star receives its slot value and a name a screen reader can announce:
+
+```vue
+<script setup lang="ts">
+import { RatingRoot, RatingStar } from "./rating-parts"
+</script>
+
+<template>
+  <RatingRoot :default-value="4" aria-label="Rating" class="flex gap-1">
+    <RatingStar
+      v-for="star in 5"
+      :key="star"
+      :value="String(star)"
+      :aria-label="`${star} ${star === 1 ? 'star' : 'stars'}`"
+      class="opacity-40 data-filled:opacity-100"
+      >★</RatingStar
+    >
+  </RatingRoot>
+</template>
+```
+
+The primitive supplies `data-filled`; these classes make the filled stars easier to see. [Styling and Animation](./styling-and-animation.md) covers other ways to style parts.
+
+Generated parts also support the same default and `#render` slots as the components in the catalog. Use [Parts and Composition](./parts-and-composition.md) when you want to change their markup.
+
+## Add Logic to a Part
+
+Keep `createParts` when mapping slots to elements is enough. [Custom Parts](./custom-parts.md) uses the same rating to show how `usePrimitive` and `usePart` let you write your own root or child part.

package/docs/server-rendering.md

@@ -0,0 +1,180 @@
+# Server Rendering
+
+Render initial HTML on the server and add interactions in the browser.
+
+ui-sdk parts render HTML with Vue's server renderer. Their initial attributes include ARIA state and the group's tab stop. In Nuxt, pages and components render this way with no plugin or module.
+
+## Render the Initial State
+
+```vue
+<script setup lang="ts">
+import { Toggle } from "@ui-sdk/vue/toggle"
+</script>
+
+<template>
+  <Toggle default-pressed>Bold</Toggle>
+</template>
+```
+
+The server sends a button with `aria-pressed="true"`. It can toggle after hydration. Native HTML behavior, such as submitting a form, can work before hydration.
+
+## Read Browser Values After Mount
+
+The server does not know the browser’s language. Start with the same placeholder on the server and client, then read the language after mount:
+
+```vue
+<script setup lang="ts">
+import { onMounted, ref } from "vue"
+
+const language = ref("")
+onMounted(() => {
+  language.value = navigator.language
+})
+</script>
+
+<template>
+  <p>{{ language || "Loading language…" }}</p>
+</template>
+```
+
+Both initial renders show “Loading language…”. Once mounted, the paragraph shows the browser’s language. Read other browser-only values in the same place, or in an event handler.
+
+## Saved Preferences and Storage
+
+Preferences like a color scheme or an emoji skin tone are saved in the browser, so the server can't render them. [Preferences](./core.md#preferences) covers the preferences themselves; this is how they fit server rendering.
+
+### Show Them Before Hydration
+
+Render `Preferences` around your app. On the server it renders one inline script as its first child, which puts every saved value on its `data-*` attribute as the page loads, before Vue hydrates, so CSS that selects those attributes is right from the first paint:
+
+```vue title="app.vue"
+<script setup lang="ts">
+import { Preferences } from "@ui-sdk/vue/preferences"
+import Page from "./page.vue"
+import { colorScheme, skinTone } from "./preferences"
+
+const preferences = [colorScheme, skinTone]
+</script>
+
+<template>
+  <Preferences :preferences="preferences">
+    <Page />
+  </Preferences>
+</template>
+```
+
+Its element marks its attributes with `data-allow-mismatch="attribute"`, since the script changes them before hydration. A preference made with `global: true` goes on `<html>` instead. Pass `nonce` if your Content Security Policy only allows inline scripts with one.
+
+Content that reads a preference through `usePreference` renders the default on the server and the saved value once mounted. Style by the attribute instead wherever the first paint has to be right, as [Style by Preferences](./core.md#style-by-preferences) shows.
+
+### Read a Cookie on the Server
+
+A preference kept in a cookie can render on the server too, content included. Read the request's `Cookie` header on the server, however your server or framework gives you the request, and pass it to your app as a prop, like `createSSRApp(App, { cookie })`. `setup` runs once per request, so create the preference there and share it with `provide`:
+
+```vue title="app.vue"
+<script setup lang="ts">
+import { createCookieStorage, createPreference } from "@ui-sdk/core"
+import { Preferences } from "@ui-sdk/vue/preferences"
+import { provide } from "vue"
+import Page from "./page.vue"
+
+const props = defineProps<{ cookie: string | null }>()
+const skinTone = createPreference({
+  values: ["default", "light", "medium", "dark"],
+  defaultValue: "default",
+  attribute: "data-skin-tone",
+  storage: createCookieStorage("skin-tone", { cookie: props.cookie }),
+})
+provide("skin-tone", skinTone)
+</script>
+
+<template>
+  <Preferences :preferences="[skinTone]">
+    <Page />
+  </Preferences>
+</template>
+```
+
+The server reads the value from `cookie`, and the browser from `document.cookie`, so both render it and hydration matches.
+
+Nuxt creates the app for you, so read the header with `useRequestHeader` in `app.vue` instead of taking a prop:
+
+```vue title="app.vue"
+<script setup lang="ts">
+import { createCookieStorage, createPreference } from "@ui-sdk/core"
+import { Preferences } from "@ui-sdk/vue/preferences"
+
+const skinTone = createPreference({
+  values: ["default", "light", "medium", "dark"],
+  defaultValue: "default",
+  attribute: "data-skin-tone",
+  storage: createCookieStorage("skin-tone", {
+    cookie: useRequestHeader("cookie"),
+  }),
+})
+provide("skin-tone", skinTone)
+</script>
+
+<template>
+  <Preferences :preferences="[skinTone]">
+    <NuxtPage />
+  </Preferences>
+</template>
+```
+
+`useRequestHeader` returns the whole `Cookie` header on the server and undefined in the browser, where the storage reads `document.cookie` instead. `useCookie` doesn't fit here, since it reads one cookie by name and the storage takes the header.
+
+### Render the Storage Script Yourself
+
+`Preferences` is the usual way. For one component that keeps its own value, like a toolbar's density, a storage's `script` returns the same kind of inline script for a single element. Render it right after the element, since it writes to the element right before it. Vue templates leave `<script>` tags out, so render it from a render function:
+
+```ts title="toolbar.ts"
+import { createLocalStorage } from "@ui-sdk/core"
+import { defineComponent, h, onMounted, shallowRef } from "vue"
+
+const density = createLocalStorage("density")
+const script = density.script({
+  attribute: "data-density",
+  values: ["comfortable", "compact"],
+})
+
+const Toolbar = defineComponent((_props, { slots }) => {
+  const value = shallowRef("comfortable")
+  // The script is in the server's HTML until then.
+  const mounted = shallowRef(false)
+  onMounted(() => {
+    value.value = density.get() === "compact" ? "compact" : "comfortable"
+    mounted.value = true
+  })
+  return () => [
+    h(
+      "div",
+      { "data-density": value.value, "data-allow-mismatch": "attribute" },
+      slots.default?.()
+    ),
+    mounted.value || !script ? null : h("script", { innerHTML: script }),
+  ]
+})
+
+export { Toolbar }
+```
+
+- **Only from the server.** The browser never runs a script Vue inserts, so drop it once mounted.
+- **The element differs until hydration.** The script changes its attribute before Vue hydrates, so mark it with `data-allow-mismatch="attribute"`. Once mounted, render the saved value from state, as above.
+- **Shared by ID.** Every script with the same storage kind and ID reads the storage once, however many elements render it, and the scripts are identical, so compression shrinks the repeats.
+- **Only safe values.** Any script on your site can write the saved value, so `script` only sets attributes that start with `data-`, and only to one of `values`.
+- **Not for cookies.** A cookie storage's `script` returns undefined, since the server reads the cookie and renders the value itself.
+
+To run before the page's content at all, render `preferencesScript([...])` from `@ui-sdk/core` in `<head>` yourself, wherever your server writes it. Only global preferences make sense there, since the others go on the script's parent element.
+
+## Keep IDs and Values Consistent
+
+Use the same initial component values on the server and client. For example, do not render an open dialog on the server and a closed one for the first client render.
+
+Parts generate IDs for relationships such as a Dialog trigger’s `aria-controls` and a Field label’s `for`. You usually do not need to supply them.
+
+Pass an explicit `id` when something outside the component needs to refer to a part. On the server, render order matters: if a Field label renders before a control with your ID, the label initially uses the generated ID. Hydration updates the reference to yours. The same applies to Dialog triggers, titles, and descriptions.
+
+Use classes or data attributes for styling, rather than generated IDs.
+
+Popups render in place, so your server layout doesn't need a portal root. [Popups](./popups.md) covers containers; [Forms](./forms.md) covers submission and validation.

package/docs/state-and-events.md

@@ -0,0 +1,100 @@
+# State and Events
+
+Set an initial value, control it, and respond to changes.
+
+Components manage their own state unless you pass a controlled value. A change callback lets you respond in either case.
+
+## Set the Starting Value
+
+Use a default prop to choose the starting state. Here, Bold starts pressed and changes when you click it:
+
+```vue
+<script setup lang="ts">
+import { Toggle } from "@ui-sdk/vue/toggle"
+</script>
+
+<template>
+  <Toggle default-pressed>Bold</Toggle>
+</template>
+```
+
+The prop depends on the component: `default-pressed`, `default-checked`, `default-open`, or `default-value`.
+
+## Control the Value
+
+Use `v-model` when the parent needs the current value:
+
+```vue
+<script setup lang="ts">
+import { Toggle } from "@ui-sdk/vue/toggle"
+import { ref } from "vue"
+
+const pressed = ref(false)
+</script>
+
+<template>
+  <Toggle v-model="pressed">Bold</Toggle>
+  <output>{{ pressed ? "On" : "Off" }}</output>
+</template>
+```
+
+`v-model` keeps the toggle’s `pressed` value in your ref. `v-model:pressed` works here too. Clicking Bold changes both the button and the output.
+
+The main value depends on the component: `checked` for Checkbox, `open` for Popover, and `value` for Select. Name another binding when you need it, such as `v-model:open` on Select or `v-model:query` on Combobox.
+
+If you pass `:pressed` without `v-model`, update that value yourself in `@pressed-change`. A value the parent never updates stays fixed.
+
+To keep a value in the URL, update your ref through `v-model` or the event, then call `router.push`. A value that changes only when the navigation finishes leaves the component showing the old one until then, and logs a warning in development.
+
+## Respond to a Change
+
+Events such as `@pressed-change` receive the requested value and `details`. They run before `v-model` updates.
+
+| Detail     | What It Tells You                                                                                |
+| ---------- | ------------------------------------------------------------------------------------------------ |
+| `reason`   | What requested the change, such as `press` or `outside-press`. Each component lists its reasons. |
+| `event`    | The DOM event, when there is one.                                                                |
+| `source`   | `keyboard`, `mouse`, `touch`, `pen`, `virtual`, `programmatic`, or `agent`.                      |
+| `cancel()` | Stops the requested change.                                                                      |
+
+For example, keep a popover open when someone clicks outside it:
+
+```vue
+<script setup lang="ts">
+import {
+  Popover,
+  PopoverClose,
+  PopoverContent,
+  PopoverTitle,
+  PopoverTrigger,
+} from "@ui-sdk/vue/popover"
+
+function keepOpen(
+  open: boolean,
+  details: { reason: string; cancel: () => void }
+) {
+  if (!open && details.reason === "outside-press") {
+    details.cancel()
+  }
+}
+</script>
+
+<template>
+  <Popover @open-change="keepOpen">
+    <PopoverTrigger>Details</PopoverTrigger>
+    <PopoverContent>
+      <PopoverTitle>Project Details</PopoverTitle>
+      <p>Last updated today.</p>
+      <PopoverClose>Done</PopoverClose>
+    </PopoverContent>
+  </Popover>
+</template>
+```
+
+The Done button still closes it. Cancellation also works when you control the value. Add `debug` to a root to log changes while you work.
+
+## Empty and Multiple Values
+
+Select, Tabs, and Radio Group report `null` when nothing is selected. A multiple Select or Combobox uses an array. Accordion and Toggle Group always use arrays.
+
+To change a component from outside its parts, use a [Controller](./controllers.md).

package/docs/styling-and-animation.md

@@ -0,0 +1,148 @@
+# Styling and Animation
+
+Style parts and their state, then add entry and exit transitions.
+
+Parts render without styles. The component demos use plain CSS, and the same state attributes and CSS variables work with Tailwind CSS or any other stylesheet.
+
+## Style a Part
+
+Every part has a `data-slot` attribute. State adds attributes such as `data-pressed` and `data-disabled`:
+
+```vue
+<script setup lang="ts">
+import { Toggle } from "@ui-sdk/vue/toggle"
+</script>
+
+<template>
+  <Toggle
+    class="rounded-md border border-neutral-300 px-2.5 py-1.5 text-sm data-pressed:bg-neutral-100 data-disabled:opacity-50"
+    >Bold</Toggle
+  >
+</template>
+```
+
+Vue's `class` and `style` bindings accept strings, arrays, and objects. They aren't functions of the part's state. Use data attributes, or read `state` in a `#render` slot.
+
+Most state attributes are present or absent. Others have values, such as `data-side="top"`. Each component's Styling section lists its attributes and CSS variables. Use those rather than generated IDs.
+
+## CSS Modules
+
+Import a CSS Module and pass its class to the part. State selectors work the same way:
+
+```vue
+<script setup lang="ts">
+import { Toggle } from "@ui-sdk/vue/toggle"
+import styles from "./toggle.module.css"
+</script>
+
+<template>
+  <Toggle :class="styles.toggle">Bold</Toggle>
+</template>
+```
+
+```css title="toggle.module.css"
+.toggle {
+  cursor: default;
+  border: 1px solid var(--input, #e5e5e5);
+  border-radius: 1.125rem;
+  background: transparent;
+  padding: 0.375rem 0.625rem;
+  color: inherit;
+  font: inherit;
+  font-size: 0.875rem;
+}
+
+.toggle[data-pressed] {
+  background: var(--muted, #f5f5f5);
+}
+
+.toggle[data-disabled] {
+  opacity: 0.5;
+}
+
+.toggle:focus-visible {
+  outline: 2px solid var(--ring, #a3a3a3);
+  outline-offset: 2px;
+}
+```
+
+## Animate Opening and Closing
+
+Popup content gets `data-starting-style` before it enters and `data-ending-style` while it exits. It stays mounted until the exit transition or animation finishes:
+
+```vue
+<script setup lang="ts">
+import {
+  Popover,
+  PopoverClose,
+  PopoverContent,
+  PopoverTitle,
+  PopoverTrigger,
+} from "@ui-sdk/vue/popover"
+</script>
+
+<template>
+  <Popover>
+    <PopoverTrigger>Details</PopoverTrigger>
+    <PopoverContent
+      class="origin-(--transform-origin) transition-[opacity,scale] duration-150 data-starting-style:scale-96 data-starting-style:opacity-0 data-ending-style:scale-96 data-ending-style:opacity-0 motion-reduce:transition-none"
+    >
+      <PopoverTitle>Project Details</PopoverTitle>
+      <p>Last updated today.</p>
+      <PopoverClose>Done</PopoverClose>
+    </PopoverContent>
+  </Popover>
+</template>
+```
+
+Put exit styles on `data-ending-style`. `data-closed` describes the state but doesn't keep the element around for an exit.
+
+Popups provide `--anchor-width` and `--available-height` for sizing. [Popups](./popups.md) covers mounting and placement.
+
+## The ui-sdk Layer
+
+A few behaviors need a little CSS, like keeping a closed popup hidden or dimming the page behind a sheet, so ui-sdk adds it to the page in a cascade layer named `ui-sdk`. Declare that layer at the top of your global stylesheet, the one `main.ts` or `nuxt.config.ts` loads, so your own styles win over it wherever the page puts them. With Tailwind, put it above `@import "tailwindcss"`:
+
+```css
+@layer ui-sdk;
+```
+
+A component's `<style>` block loads with the component, too late to come first, so keep the line in the global stylesheet.
+
+ui-sdk adds this CSS once a component mounts, so HTML rendered on the server doesn't have it until the page hydrates. Closed content kept in the page, like a tooltip's, carries `hidden`, and a class that sets `display` shows it until then. Tailwind's base styles already hide `hidden` elements. With other CSS, add the same rule to your global stylesheet:
+
+```css
+@layer ui-sdk {
+  :where([data-slot][hidden]:not([hidden="until-found"])) {
+    display: none !important;
+  }
+}
+```
+
+It leaves `hidden="until-found"` alone, so find in page can still open a closed panel.
+
+## Content Security Policy
+
+A Content Security Policy without `'unsafe-inline'` in `style-src` blocks the CSS ui-sdk adds. Give ui-sdk your policy's nonce with a meta tag in the page's `<head>`:
+
+```html
+<meta property="csp-nonce" nonce="your-nonce" />
+```
+
+With Vite, set `html.cspNonce` in your Vite config to a placeholder, and Vite writes this tag for you. Your server replaces the placeholder with a new nonce on each request.
+
+In Nuxt, the nuxt-security module writes the tag only in development. For production, add a Nitro plugin, like `server/plugins/csp-nonce.ts`, that writes it into every page with the module's nonce:
+
+```ts
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook("render:html", (html, { event }) => {
+    html.head.push(
+      `<meta property="csp-nonce" nonce="${event.context.security.nonce}">`
+    )
+  })
+})
+```
+
+Pages rendered on the server also carry a few `style` attributes, like the one that hides a select's native input, so the policy needs `style-src-attr 'unsafe-inline'` too.
+
+If your policy has no nonce for styles, add the tag without the `nonce` attribute. ui-sdk then adds its CSS as constructed style sheets, which no policy blocks. In Nuxt, `useHead` leaves out a meta tag without `content`, so give it one. ui-sdk doesn't read it: `useHead({ meta: [{ property: "csp-nonce", content: "none" }] })`. If your code replaces `document.adoptedStyleSheets`, ui-sdk adds its sheets back the next time a component mounts.