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

package/docs/styling-and-animation.md

@@ -0,0 +1,176 @@
+# 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-open`, `data-pressed`, or `data-disabled`:
+
+```tsx
+import { Toggle } from "@ui-sdk/react/toggle"
+
+function Example() {
+  return (
+    <Toggle className="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>
+  )
+}
+
+export { Example }
+```
+
+Most state attributes are present or absent. Others have values, such as `data-side="top"` or `data-orientation="vertical"`. Each component's Styling section lists its attributes and CSS variables. Use these rather than generated IDs, which can change.
+
+## CSS Modules
+
+Import a CSS Module and pass its class to the part. State selectors work the same way:
+
+```tsx
+import { Toggle } from "@ui-sdk/react/toggle"
+import styles from "./toggle.module.css"
+
+function Example() {
+  return <Toggle className={styles.toggle}>Bold</Toggle>
+}
+
+export { Example }
+```
+
+```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;
+}
+```
+
+## Use State in React
+
+`className` and `style` can be functions of the part's state:
+
+```tsx
+"use client"
+
+import { Toggle } from "@ui-sdk/react/toggle"
+
+function Example() {
+  return (
+    <Toggle
+      className={(state) => (state.pressed ? "font-bold" : "font-normal")}
+    >
+      Bold
+    </Toggle>
+  )
+}
+
+export { Example }
+```
+
+With Tailwind, you can also use attribute variants, such as `data-pressed:font-bold`.
+
+## Animate Opening and Closing
+
+Popup content gets `data-starting-style` before it enters and `data-ending-style` while it exits. The content stays mounted until its exit transition or animation finishes.
+
+```tsx
+import { Popover, PopoverContent, PopoverTrigger } from "@ui-sdk/react/popover"
+
+function Example() {
+  return (
+    <Popover>
+      <PopoverTrigger>Details</PopoverTrigger>
+      <PopoverContent
+        aria-label="Project details"
+        className="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"
+      >
+        Last updated today.
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+export { Example }
+```
+
+Put exit styles on `data-ending-style`. `data-closed` describes the state, but doesn't keep the element around for an exit.
+
+Popups also provide `--anchor-width` and `--available-height` for sizing. If an animation library needs closed content to stay mounted, use `keepMounted`. See [Popups](./popups.md) for placement and mounting options.
+
+## 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 your app's entry or root layout imports, so your own styles win over it wherever the page puts them. With Tailwind, put it above `@import "tailwindcss"`:
+
+```css
+@layer ui-sdk;
+```
+
+A CSS Module loads with its 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 Next.js, render the tag in the root layout's `<head>`, with the nonce your middleware passes in a request header:
+
+```tsx
+import { headers } from "next/headers"
+
+export default async function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const nonce = (await headers()).get("x-nonce") ?? undefined
+  return (
+    <html lang="en">
+      <head>
+        <meta property="csp-nonce" nonce={nonce} />
+      </head>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+
+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. If your code replaces `document.adoptedStyleSheets`, ui-sdk adds its sheets back the next time a component mounts.

package/package.json

@@ -1,6 +1,336 @@
 {
   "name": "@ui-sdk/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-beta.1",
+  "description": "UI SDK for React.",
+  "keywords": [
+    "react",
+    "ui",
+    "ui-sdk",
+    "shadcn",
+    "behaviors",
+    "accessibility",
+    "a11y",
+    "aria",
+    "keyboard",
+    "focus",
+    "headless",
+    "unstyled",
+    "components",
+    "agents"
+  ],
+  "type": "module",
+  "license": "Apache-2.0",
+  "homepage": "https://ui-sdk.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vercel-labs/ui.git",
+    "directory": "packages/react"
+  },
+  "bugs": "https://github.com/vercel-labs/ui/issues",
+  "exports": {
+    "./accordion": {
+      "types": "./dist/accordion.d.ts",
+      "default": "./dist/accordion.js"
+    },
+    "./alert-dialog": {
+      "types": "./dist/alert-dialog.d.ts",
+      "default": "./dist/alert-dialog.js"
+    },
+    "./async-options": {
+      "types": "./dist/async-options.d.ts",
+      "default": "./dist/async-options.js"
+    },
+    "./autocomplete": {
+      "types": "./dist/autocomplete.d.ts",
+      "default": "./dist/autocomplete.js"
+    },
+    "./avatar": {
+      "types": "./dist/avatar.d.ts",
+      "default": "./dist/avatar.js"
+    },
+    "./button": {
+      "types": "./dist/button.d.ts",
+      "default": "./dist/button.js"
+    },
+    "./calendar": {
+      "types": "./dist/calendar.d.ts",
+      "default": "./dist/calendar.js"
+    },
+    "./carousel": {
+      "types": "./dist/carousel.d.ts",
+      "default": "./dist/carousel.js"
+    },
+    "./checkbox": {
+      "types": "./dist/checkbox.d.ts",
+      "default": "./dist/checkbox.js"
+    },
+    "./collapsible": {
+      "types": "./dist/collapsible.d.ts",
+      "default": "./dist/collapsible.js"
+    },
+    "./color": {
+      "types": "./dist/color.d.ts",
+      "default": "./dist/color.js"
+    },
+    "./color-picker": {
+      "types": "./dist/color-picker.d.ts",
+      "default": "./dist/color-picker.js"
+    },
+    "./combobox": {
+      "types": "./dist/combobox.d.ts",
+      "default": "./dist/combobox.js"
+    },
+    "./command": {
+      "types": "./dist/command.d.ts",
+      "default": "./dist/command.js"
+    },
+    "./date": {
+      "types": "./dist/date.d.ts",
+      "default": "./dist/date.js"
+    },
+    "./date-input": {
+      "types": "./dist/date-input.d.ts",
+      "default": "./dist/date-input.js"
+    },
+    "./date-picker": {
+      "types": "./dist/date-picker.d.ts",
+      "default": "./dist/date-picker.js"
+    },
+    "./dialog": {
+      "types": "./dist/dialog.d.ts",
+      "default": "./dist/dialog.js"
+    },
+    "./drawer": {
+      "types": "./dist/drawer.d.ts",
+      "default": "./dist/drawer.js"
+    },
+    "./field": {
+      "types": "./dist/field.d.ts",
+      "default": "./dist/field.js"
+    },
+    "./file-input": {
+      "types": "./dist/file-input.d.ts",
+      "default": "./dist/file-input.js"
+    },
+    "./gesture": {
+      "types": "./dist/gesture.d.ts",
+      "default": "./dist/gesture.js"
+    },
+    "./hover-card": {
+      "types": "./dist/hover-card.d.ts",
+      "default": "./dist/hover-card.js"
+    },
+    "./image": {
+      "types": "./dist/image.d.ts",
+      "default": "./dist/image.js"
+    },
+    "./image-cropper": {
+      "types": "./dist/image-cropper.d.ts",
+      "default": "./dist/image-cropper.js"
+    },
+    "./input": {
+      "types": "./dist/input.d.ts",
+      "default": "./dist/input.js"
+    },
+    "./label": {
+      "types": "./dist/label.d.ts",
+      "default": "./dist/label.js"
+    },
+    "./listbox": {
+      "types": "./dist/listbox.d.ts",
+      "default": "./dist/listbox.js"
+    },
+    "./menu": {
+      "types": "./dist/menu.d.ts",
+      "default": "./dist/menu.js"
+    },
+    "./menubar": {
+      "types": "./dist/menubar.d.ts",
+      "default": "./dist/menubar.js"
+    },
+    "./meter": {
+      "types": "./dist/meter.d.ts",
+      "default": "./dist/meter.js"
+    },
+    "./navigation-menu": {
+      "types": "./dist/navigation-menu.d.ts",
+      "default": "./dist/navigation-menu.js"
+    },
+    "./number": {
+      "types": "./dist/number.d.ts",
+      "default": "./dist/number.js"
+    },
+    "./number-input": {
+      "types": "./dist/number-input.d.ts",
+      "default": "./dist/number-input.js"
+    },
+    "./otp-input": {
+      "types": "./dist/otp-input.d.ts",
+      "default": "./dist/otp-input.js"
+    },
+    "./overlays": {
+      "types": "./dist/overlays.d.ts",
+      "default": "./dist/overlays.js"
+    },
+    "./pagination": {
+      "types": "./dist/pagination.d.ts",
+      "default": "./dist/pagination.js"
+    },
+    "./password-input": {
+      "types": "./dist/password-input.d.ts",
+      "default": "./dist/password-input.js"
+    },
+    "./popover": {
+      "types": "./dist/popover.d.ts",
+      "default": "./dist/popover.js"
+    },
+    "./primitive": {
+      "types": "./dist/primitive.d.ts",
+      "default": "./dist/primitive.js"
+    },
+    "./preferences": {
+      "types": "./dist/preferences.d.ts",
+      "default": "./dist/preferences.js"
+    },
+    "./progress": {
+      "types": "./dist/progress.d.ts",
+      "default": "./dist/progress.js"
+    },
+    "./radio": {
+      "types": "./dist/radio.d.ts",
+      "default": "./dist/radio.js"
+    },
+    "./rating": {
+      "types": "./dist/rating.d.ts",
+      "default": "./dist/rating.js"
+    },
+    "./resizable": {
+      "types": "./dist/resizable.d.ts",
+      "default": "./dist/resizable.js"
+    },
+    "./scroll-area": {
+      "types": "./dist/scroll-area.d.ts",
+      "default": "./dist/scroll-area.js"
+    },
+    "./segmented-control": {
+      "types": "./dist/segmented-control.d.ts",
+      "default": "./dist/segmented-control.js"
+    },
+    "./select": {
+      "types": "./dist/select.d.ts",
+      "default": "./dist/select.js"
+    },
+    "./separator": {
+      "types": "./dist/separator.d.ts",
+      "default": "./dist/separator.js"
+    },
+    "./shortcuts": {
+      "types": "./dist/shortcuts.d.ts",
+      "default": "./dist/shortcuts.js"
+    },
+    "./slider": {
+      "types": "./dist/slider.d.ts",
+      "default": "./dist/slider.js"
+    },
+    "./switch": {
+      "types": "./dist/switch.d.ts",
+      "default": "./dist/switch.js"
+    },
+    "./tabs": {
+      "types": "./dist/tabs.d.ts",
+      "default": "./dist/tabs.js"
+    },
+    "./text-match": {
+      "types": "./dist/text-match.d.ts",
+      "default": "./dist/text-match.js"
+    },
+    "./agent": {
+      "types": "./dist/agent.d.ts",
+      "default": "./dist/agent.js"
+    },
+    "./observe": {
+      "types": "./dist/observe.d.ts",
+      "default": "./dist/observe.js"
+    },
+    "./history": {
+      "types": "./dist/history.d.ts",
+      "default": "./dist/history.js"
+    },
+    "./textarea": {
+      "types": "./dist/textarea.d.ts",
+      "default": "./dist/textarea.js"
+    },
+    "./time-input": {
+      "types": "./dist/time-input.d.ts",
+      "default": "./dist/time-input.js"
+    },
+    "./timeline": {
+      "types": "./dist/timeline.d.ts",
+      "default": "./dist/timeline.js"
+    },
+    "./toast": {
+      "types": "./dist/toast.d.ts",
+      "default": "./dist/toast.js"
+    },
+    "./toggle": {
+      "types": "./dist/toggle.d.ts",
+      "default": "./dist/toggle.js"
+    },
+    "./token-input": {
+      "types": "./dist/token-input.d.ts",
+      "default": "./dist/token-input.js"
+    },
+    "./toolbar": {
+      "types": "./dist/toolbar.d.ts",
+      "default": "./dist/toolbar.js"
+    },
+    "./tooltip": {
+      "types": "./dist/tooltip.d.ts",
+      "default": "./dist/tooltip.js"
+    },
+    "./tree": {
+      "types": "./dist/tree.d.ts",
+      "default": "./dist/tree.js"
+    },
+    "./trigger-menu": {
+      "types": "./dist/trigger-menu.d.ts",
+      "default": "./dist/trigger-menu.js"
+    },
+    "./waterfall": {
+      "types": "./dist/waterfall.d.ts",
+      "default": "./dist/waterfall.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "peerDependencies": {
+    "@types/react": ">=19.2.10",
+    "react": ">=19",
+    "react-dom": ">=19",
+    "@ui-sdk/core": "^0.1.0-beta.1"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "~19.2.2",
+    "@types/react-dom": "~19.2.2",
+    "jsdom": "^30.1.2",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "typescript": "~5.9.3",
+    "vitest": "^5.0.3",
+    "@ui-sdk/core": "0.1.0-beta.1"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build/build-package.mjs --use-client --server primitive.ts --server render-element.ts",
+    "typecheck": "node ../../scripts/tsgo.mjs --noEmit && node ../../scripts/tsgo.mjs --noEmit -p tsconfig.test.json",
+    "test": "vitest run"
+  }
 }