@nextlyhq/ui 0.0.2-alpha.35 → 0.0.2-alpha.39

package/README.md

@@ -31,7 +31,7 @@ pnpm add react react-dom lucide-react
 
 ## Setup
 
-The package ships two CSS entry points. Pick one:
+The package ships three CSS entry points. Pick one:
 
 **Zero config — pre-compiled bundle**
 
@@ -58,10 +58,10 @@ utilities the components use:
 @source "../node_modules/@nextlyhq/ui/dist";
 ```
 
-`theme.css` defines the tokens as complete OKLCH color values (`--background`, `--primary`,
-`--border`, …) with `@theme inline` mappings and the dark-mode overrides. Reference tokens
-directly (`var(--primary)`) — never wrap them in `hsl()`. The exported `uiPreset` remains
-available as a Tailwind v3 preset.
+`theme.css` defines the tokens as complete OKLCH color values (`--nx-background`, `--nx-primary`,
+`--nx-border`, …) with `@theme inline` mappings and the dark-mode overrides. Reference tokens
+directly (`var(--nx-primary)`) — never wrap them in `hsl()`. `uiPreset` remains available
+as a Tailwind v3 preset from `@nextlyhq/ui/tailwind-preset`.
 
 > Inside a Nextly admin plugin you need neither import — the admin already provides the
 > tokens. See the [**Plugin UI authoring guide**](./docs/plugin-ui-authoring.md).
@@ -77,15 +77,81 @@ available as a Tailwind v3 preset.
 **Feedback:** `Spinner`, `Toaster` (with `toast()` helper)
 **Tables:** `Table` primitives, `ResponsiveTable`, `TableSearch`, `TablePagination`, `TableSkeleton`, `TableEmpty`, `TableError`, `TableLoading`
 **Providers:** `PortalProvider`, `usePortalContainer`
-**Utilities:** `cn`, `uiPreset`
+
+> Which of these carry a stability guarantee is recorded in
+> [STABILITY.md](https://github.com/nextlyhq/nextly/blob/main/packages/ui/STABILITY.md). A component becomes `@public` once a first-party
+> plugin depends on it; everything else is `@experimental` and may change in any
+> release.
+
+**Utilities:** `cn` (from `@nextlyhq/ui/utils`), `uiPreset` (from `@nextlyhq/ui/tailwind-preset`)
+
+> Both ship from their own subpaths rather than the root: the root bundle is
+> published with `"use client"`, and neither of these contains a React runtime,
+> so a server component or a Tailwind config can import them safely.
+
+## Stylesheets
+
+| Import                           | Use when                                                                                                                              |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `@nextlyhq/ui/styles.css`        | The app is yours end to end. Styles the whole document, Tailwind preflight included.                                                  |
+| `@nextlyhq/ui/styles.scoped.css` | Dropping a few components into an existing app. Every rule is confined to `.nextly-ui`, so the rest of the page keeps its own styles. |
+| `@nextlyhq/ui/theme.css`         | You compile Tailwind yourself and want the token contract only.                                                                       |
+
+The scoped sheet needs a wrapper element, and dark mode goes on the same element:
+
+```tsx
+import "@nextlyhq/ui/styles.scoped.css";
+
+<div className="nextly-ui">
+  <Button>Save</Button>
+</div>;
+```
+
+It keeps preflight rather than dropping it — these components are designed against a
+normalised baseline — but confines it to the wrapper, so your headings, lists and form
+controls outside it are untouched. Three things CSS resolves globally are namespaced
+along with the selectors, so the sheet cannot reach outside the wrapper through them
+either: animation names (it will not displace a `spin` or `fade-in` you define),
+Tailwind's internal `--tw-*` registrations, and the ancestor classes `dark:` and
+`group-*:` variants look for. Dark mode is therefore driven by the wrapper, not by a
+`dark` class higher up your page.
+
+### Overlays need a portal container
+
+AlertDialog, Command, Dialog, DropdownMenu, Popover, Select, Sheet and Tooltip render
+their overlay through a portal, which defaults to `document.body` — outside the wrapper,
+where the scoped rules and tokens do not reach. Triggers would look right and the menus
+they open would not. Point them back inside with `PortalProvider`:
+
+```tsx
+import { useState } from "react";
+import { PortalProvider } from "@nextlyhq/ui";
+import "@nextlyhq/ui/styles.scoped.css";
+
+function Kit({ children }: { children: React.ReactNode }) {
+  const [container, setContainer] = useState<HTMLElement | null>(null);
+
+  return (
+    <div className="nextly-ui" ref={setContainer}>
+      <PortalProvider container={container}>{children}</PortalProvider>
+    </div>
+  );
+}
+```
+
+A callback ref rather than `useRef` because the container has to be a state value: on the
+first render it is still `null`, and the overlays need a re-render once the element exists.
+
+This does not apply to `styles.css`, where the rules are document-wide and
+`document.body` is already covered.
 
 ## Compatibility
 
-| Tool           | Version                                                          |
-| -------------- | ---------------------------------------------------------------- |
-| React          | 18 or 19                                                         |
-| Tailwind CSS   | 4+ (the `uiPreset` JS export also works as a Tailwind v3 preset) |
-| `lucide-react` | 0.400+                                                           |
+| Tool           | Version                                                                |
+| -------------- | ---------------------------------------------------------------------- |
+| React          | 18 or 19                                                               |
+| Tailwind CSS   | 4+ (`@nextlyhq/ui/tailwind-preset` also works as a Tailwind v3 preset) |
+| `lucide-react` | 0.400+                                                                 |
 
 ## Documentation