prime-ui-kit 0.3.2 → 0.4.0

package/src/components/page-content/COMPONENT.md

@@ -0,0 +1,123 @@
+# PageContent
+
+## About
+
+Semantic **page column** primitives: **`PageContent.Section`** (a **`<section>`** page region without its own outer padding), **`PageContent.Root`** (full padded column with optional **`maxWidth`**), **`PageContent.Title`** → **`<h1>`**, **`PageContent.Description`** with **`measure`**, and **`PageContent.Body`**. Typography uses kit tokens.
+
+- **Use `PageContent.Section`** when the shell (e.g. **`AppShell.Main`** with `variant="page"`) already applies padding — same pattern as playground routes, without wrapping in **`Root`**.
+- **Use `PageContent.Root`** when you need that outer padding and optional **`maxWidth`** (`full` | `readable` | `wide`; default **`full`**).
+- **Use `Description` `measure="full"`** when the parent column is already inset; default **`measure="readable"`** keeps the lead ~65ch for reading.
+
+## Composition
+
+- **`PageContent.Root`** — outer wrapper: padding + optional max-width (`data-max-width`).
+- **`PageContent.Section`** — **`<section>`** without extra outer padding; pair with **`aria-labelledby`** pointing at **`PageContent.Title`** `id`.
+- **`PageContent.Header`** — stacks title + description with spacing.
+- **`PageContent.Title`** — **`<h1>`** (one per route).
+- **`PageContent.Description`** — **`<p>`** lead; **`measure`** controls max width.
+- **`PageContent.Body`** — main blocks below the header (demos, forms, tables).
+
+### Canonical example (inside padded `main`)
+
+```tsx
+import { PageContent } from "prime-ui-kit";
+
+export function DocRouteBody() {
+  return (
+    <PageContent.Section aria-labelledby="page-heading">
+      <PageContent.Header>
+        <PageContent.Title id="page-heading">Settings</PageContent.Title>
+        <PageContent.Description measure="full">
+          Manage your workspace profile and notifications.
+        </PageContent.Description>
+      </PageContent.Header>
+      <PageContent.Body>{/* page blocks */}</PageContent.Body>
+    </PageContent.Section>
+  );
+}
+```
+
+### Canonical example (standalone column)
+
+```tsx
+import { PageContent } from "prime-ui-kit";
+
+export function StandalonePage() {
+  return (
+    <PageContent.Root maxWidth="readable">
+      <PageContent.Header>
+        <PageContent.Title>Account</PageContent.Title>
+        <PageContent.Description>Billing and security.</PageContent.Description>
+      </PageContent.Header>
+      <PageContent.Body>{/* … */}</PageContent.Body>
+    </PageContent.Root>
+  );
+}
+```
+
+### Playground
+
+Live demo and API tables: **`playground/sections/PageContentSection.tsx`** — **`Section`** → **`Header`** (**`Title`**, **`Description measure="full"`**) → **`Body`**. There is no **`playground/snippets/page-content/`** tree; the section is the single demo surface.
+
+## Rules
+
+- Prefer **one** `h1` per view — **`PageContent.Title`**.
+- Do not nest **`PageContent.Root`** inside a **`main`** that already applies page padding unless you intentionally want double padding; use **`Section`** instead.
+- **`Description`** defaults to a readable measure; use **`measure="full"`** when the layout already constrains width.
+
+## API
+
+### PageContent.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| maxWidth | `full` \| `readable` \| `wide` | `full` | No | Limits the content column; drives `data-max-width` when not `full`. |
+| className | `string` | — | No | Class on the root wrapper. |
+| children | `React.ReactNode` | — | No | Header, body, nested sections. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Native `div` attributes, including `ref` (`forwardRef`). |
+
+### PageContent.Section
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class on **`<section>`** (page region without outer padding—typical inside padded `main`). |
+| children | `React.ReactNode` | — | No | Usually **`Header`** + **`Body`** (playground routes follow this). |
+| …rest | `React.HTMLAttributes<HTMLElement>` | — | No | Native **`<section>`** attributes, including `ref` (`forwardRef`). |
+
+### PageContent.Header
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class on the header block (title + description). |
+| children | `React.ReactNode` | — | No | Usually **`PageContent.Title`** and **`PageContent.Description`** (`measure` as needed). |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Native `div` attributes. |
+
+### PageContent.Title
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class on **`<h1>`**. |
+| children | `React.ReactNode` | — | No | Page heading. |
+| …rest | `React.HTMLAttributes<HTMLHeadingElement>` | — | No | Native **`h1`** attributes, including `ref` (`forwardRef`). |
+
+### PageContent.Description
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| measure | `readable` \| `full` | `readable` | No | `readable` — ~65ch; `full` — parent width (e.g. when **`AppShell.Main`** already insets). |
+| className | `string` | — | No | Class on the lead **`<p>`**. |
+| children | `React.ReactNode` | — | No | Intro text under the title. |
+| …rest | `React.HTMLAttributes<HTMLParagraphElement>` | — | No | Native **`p`** attributes, including `ref` (`forwardRef`). |
+
+### PageContent.Body
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class on the main content wrapper below the header. |
+| children | `React.ReactNode` | — | No | Page content under the header. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Native `div` attributes. |
+
+## Related
+
+- [Typography](../typography/COMPONENT.md) — inline roles elsewhere on the page.
+- [AppShell](../../layout/app-shell/AppShell.tsx) — grid + main padding (`variant="page"`).

package/src/components/pagination/COMPONENT.md

@@ -28,15 +28,32 @@ Chunked navigation for lists and tables: chevron previous/next, numbered pages,
 - **`Pagination.Root`** — the only public part. Renders the **`nav`** row; **`className`** merges onto that **`nav`** only.
 - Full-width or “meta left / pager right” layouts are parent responsibility (flex or grid around **`Pagination.Root`**)—there is no **`fullWidth`** prop on **`Pagination`**.
 
+### Playground snippets
+
+Demos match **`playground/sections/PaginationSection.tsx`** (order and intent). Sources use **`@/`** under **`playground/snippets/pagination/`**; section descriptions and some labels are Russian in the playground UI.
+
+| Playground block | Snippet | Intent |
+|------------------|---------|--------|
+| Размеры | [`sizes.tsx`](../../../playground/snippets/pagination/sizes.tsx) (+ [`sizes.module.css`](../../../playground/snippets/pagination/sizes.module.css)) | **`size`** **`s`–`xl`**, long range (**`totalPages={20}`**), local state per row |
+| Диапазон номеров | [`range-modes.tsx`](../../../playground/snippets/pagination/range-modes.tsx) (+ [`rows.module.css`](../../../playground/snippets/pagination/rows.module.css)) | All indices when **`totalPages ≤ 7`** vs ellipsis row when larger |
+| Состояния | [`states.tsx`](../../../playground/snippets/pagination/states.tsx) | First / last / single-page arrow **`disabled`** semantics |
+| Контролируемый режим | [`controlled.tsx`](../../../playground/snippets/pagination/controlled.tsx) (+ [`controlled.module.css`](../../../playground/snippets/pagination/controlled.module.css)) | Shared **`page`** with external jump buttons |
+| Full width | [`full-width.tsx`](../../../playground/snippets/pagination/full-width.tsx) (+ [`full-width.module.css`](../../../playground/snippets/pagination/full-width.module.css)) | Flex toolbar: meta left, pager right (no **`fullWidth`** prop) |
+| Специфичные фичи | [`features.tsx`](../../../playground/snippets/pagination/features.tsx) | **`siblingCount`** **`0`** / **`2`**; **`totalPages=0`** → **`null`** |
+
 ### Scenarios (see `examples/`)
 
 | Scenario | Approach |
 |----------|----------|
+| Size ladder | Same as playground **Размеры**; package copy in English. → [`examples/sizes.tsx`](examples/sizes.tsx) |
+| Range modes | Same as playground **Диапазон номеров**. → [`examples/range-modes.tsx`](examples/range-modes.tsx) |
+| Disabled arrows / single page | Same as playground **Состояния**. → [`examples/states.tsx`](examples/states.tsx) |
+| Sibling window + empty data | Same as playground **Специфичные фичи** (`siblingCount`, `totalPages=0`). → [`examples/features.tsx`](examples/features.tsx) |
 | Table footer | Pair a range summary with **`Pagination.Root`** in a footer row; keep **`page`** in sync with fetched rows. → [`examples/table-footer.tsx`](examples/table-footer.tsx) |
 | Compact toolbar | Set **`size="s"`** for denser toolbars or mobile-adjacent rows. → [`examples/compact.tsx`](examples/compact.tsx) |
 | Full-width list bar | **`display: flex`**, **`justify-content: space-between`**, **`flex-wrap`**: meta text + pager. → [`examples/full-width-list.tsx`](examples/full-width-list.tsx) |
 | Controlled page index | Store **`page`** in React state (or router); update from **`onPageChange`** and any other controls (e.g. jump to first/last). → [`examples/controlled-page.tsx`](examples/controlled-page.tsx) |
-| Canonical wiring | Minimal **`Pagination.Root`** with required props; reference for imports and props. → [`examples/canonical-composition.tsx`](examples/canonical-composition.tsx) |
+| Canonical wiring | Minimal **`Pagination.Root`** with required props; short row + long row with **`siblingCount`**. → [`examples/canonical-composition.tsx`](examples/canonical-composition.tsx) |
 
 ### Minimal example
 
@@ -58,11 +75,15 @@ For **default wiring**, **long ranges**, and **`siblingCount`**, open **`example
 
 | File | Scenario |
 |------|----------|
-| `canonical-composition.tsx` | Required props, default size, long range + `siblingCount` |
-| `table-footer.tsx` | English table footer: row range + pager |
-| `compact.tsx` | English compact row: `size="s"` |
-| `full-width-list.tsx` | English full-width bar: summary + pager |
-| `controlled-page.tsx` | English controlled state + jump buttons |
+| `sizes.tsx` | **`size`** ladder + long range (mirror [`sizes.tsx`](../../../playground/snippets/pagination/sizes.tsx)) |
+| `range-modes.tsx` | Short vs long `totalPages` (mirror [`range-modes.tsx`](../../../playground/snippets/pagination/range-modes.tsx)) |
+| `states.tsx` | First / last / single page (mirror [`states.tsx`](../../../playground/snippets/pagination/states.tsx)) |
+| `controlled-page.tsx` | Controlled `page` + jump buttons (mirror [`controlled.tsx`](../../../playground/snippets/pagination/controlled.tsx)) |
+| `full-width-list.tsx` | Full-width bar (mirror [`full-width.tsx`](../../../playground/snippets/pagination/full-width.tsx)) |
+| `features.tsx` | `siblingCount` and `totalPages=0` (mirror [`features.tsx`](../../../playground/snippets/pagination/features.tsx)) |
+| `canonical-composition.tsx` | Required props, default size, short row + long row with `siblingCount` |
+| `table-footer.tsx` | Table footer: row range + pager |
+| `compact.tsx` | Compact row: `size="s"` |
 
 ### Rules
 
@@ -92,6 +113,7 @@ For **default wiring**, **long ranges**, and **`siblingCount`**, open **`example
 
 ## LLM note
 
+- **Playground:** demos and order — **`playground/sections/PaginationSection.tsx`** + **`playground/snippets/pagination/*.tsx`**; **`examples/`** files in the table above mirror those snippets with **`prime-ui-kit`** imports where noted.
 - **Imports:** **`import { Pagination } from "prime-ui-kit"`** — use **`Pagination.Root`** only; there is no flat **`Pagination`** element.
 - **Props:** **`page`**, **`totalPages`**, **`onPageChange`** required; optional **`siblingCount`**, **`size`**, **`className`**.
 - **`size`** literals: **`s`**, **`m`**, **`l`**, **`xl`** — default **`m`**; maps to **`data-size`** on the root **`nav`**.

package/src/components/pagination/examples/controlled-page.tsx

@@ -3,7 +3,7 @@ import * as React from "react";
 
 const TOTAL = 12;
 
-/** Page index lives in parent state; Pagination.Root and buttons share the same setter. */
+/** Page index lives in parent state; Pagination.Root and buttons share the same setter. Parity with `playground/snippets/pagination/controlled.tsx` (English copy). */
 export default function ControlledPageExample() {
   const [page, setPage] = React.useState(4);
 

package/src/components/pagination/examples/features.tsx

@@ -0,0 +1,107 @@
+import { Pagination } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * `siblingCount` widens or narrows the numeric window; `totalPages < 1` renders nothing.
+ * Parity with `playground/snippets/pagination/features.tsx`.
+ */
+export default function PaginationFeaturesExample() {
+  const [pageNarrow, setPageNarrow] = React.useState(8);
+  const [pageWide, setPageWide] = React.useState(8);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-x4)",
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: "var(--prime-sys-spacing-x2)",
+          alignItems: "flex-start",
+        }}
+      >
+        <p
+          style={{
+            margin: 0,
+            fontSize: "var(--prime-sys-size-control-s-supportText)",
+            color: "var(--prime-sys-color-content-secondary)",
+          }}
+        >
+          <code>siblingCount=0</code>
+        </p>
+        <Pagination.Root
+          page={pageNarrow}
+          totalPages={20}
+          onPageChange={setPageNarrow}
+          siblingCount={0}
+        />
+      </div>
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: "var(--prime-sys-spacing-x2)",
+          alignItems: "flex-start",
+        }}
+      >
+        <p
+          style={{
+            margin: 0,
+            fontSize: "var(--prime-sys-size-control-s-supportText)",
+            color: "var(--prime-sys-color-content-secondary)",
+          }}
+        >
+          <code>siblingCount=2</code>
+        </p>
+        <Pagination.Root
+          page={pageWide}
+          totalPages={20}
+          onPageChange={setPageWide}
+          siblingCount={2}
+        />
+      </div>
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: "var(--prime-sys-spacing-x2)",
+          alignItems: "flex-start",
+        }}
+      >
+        <p
+          style={{
+            margin: 0,
+            fontSize: "var(--prime-sys-size-control-s-supportText)",
+            color: "var(--prime-sys-color-content-secondary)",
+          }}
+        >
+          <code>totalPages=0</code>
+        </p>
+        <div
+          style={{
+            display: "flex",
+            flexWrap: "wrap",
+            alignItems: "center",
+            gap: "var(--prime-sys-spacing-x2)",
+            minHeight: "var(--prime-sys-size-control-m-height)",
+          }}
+        >
+          <Pagination.Root page={1} totalPages={0} onPageChange={() => {}} />
+          <span
+            style={{
+              fontSize: "var(--prime-sys-size-control-s-supportText)",
+              color: "var(--prime-sys-color-content-muted)",
+            }}
+          >
+            empty output
+          </span>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/pagination/examples/full-width-list.tsx

@@ -1,7 +1,7 @@
 import { Pagination } from "prime-ui-kit";
 import * as React from "react";
 
-/** Full-width bar: meta on the left, Pagination.Root on the right (parent layout). */
+/** Full-width bar: meta on the left, Pagination.Root on the right (parent layout). Parity with `playground/snippets/pagination/full-width.tsx` (English copy). */
 export default function FullWidthListExample() {
   const [page, setPage] = React.useState(2);
   const totalPages = 21;

package/src/components/pagination/examples/range-modes.tsx

@@ -0,0 +1,60 @@
+import { Pagination } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Up to seven pages: all indices shown; more pages: shortened row with ellipses (`totalPages` drives logic).
+ * Parity with `playground/snippets/pagination/range-modes.tsx`.
+ */
+export default function PaginationRangeModesExample() {
+  const [shortPage, setShortPage] = React.useState(3);
+  const [longPage, setLongPage] = React.useState(8);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-x4)",
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: "var(--prime-sys-spacing-x2)",
+          alignItems: "flex-start",
+        }}
+      >
+        <p
+          style={{
+            margin: 0,
+            fontSize: "var(--prime-sys-size-control-s-supportText)",
+            color: "var(--prime-sys-color-content-secondary)",
+          }}
+        >
+          Five pages — all numbers
+        </p>
+        <Pagination.Root page={shortPage} totalPages={5} onPageChange={setShortPage} />
+      </div>
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: "var(--prime-sys-spacing-x2)",
+          alignItems: "flex-start",
+        }}
+      >
+        <p
+          style={{
+            margin: 0,
+            fontSize: "var(--prime-sys-size-control-s-supportText)",
+            color: "var(--prime-sys-color-content-secondary)",
+          }}
+        >
+          Twenty pages — ellipsis
+        </p>
+        <Pagination.Root page={longPage} totalPages={20} onPageChange={setLongPage} />
+      </div>
+    </div>
+  );
+}

package/src/components/pagination/examples/sizes.tsx

@@ -0,0 +1,50 @@
+import { Pagination, type PaginationSize } from "prime-ui-kit";
+import * as React from "react";
+
+function PaginationSizeRow({ size }: { size: PaginationSize }) {
+  const [page, setPage] = React.useState(8);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-x2)",
+        alignItems: "flex-start",
+      }}
+    >
+      <p
+        style={{
+          margin: 0,
+          fontSize: "var(--prime-sys-size-control-s-supportText)",
+          color: "var(--prime-sys-color-content-secondary)",
+        }}
+      >
+        {size}
+      </p>
+      <Pagination.Root page={page} totalPages={20} onPageChange={setPage} size={size} />
+    </div>
+  );
+}
+
+/**
+ * Four control tiers on a long page row (arrows, numbers, ellipsis share one scale per `size`).
+ * Parity with `playground/snippets/pagination/sizes.tsx`.
+ */
+export default function PaginationSizesExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-x4)",
+        alignItems: "center",
+      }}
+    >
+      <PaginationSizeRow size="s" />
+      <PaginationSizeRow size="m" />
+      <PaginationSizeRow size="l" />
+      <PaginationSizeRow size="xl" />
+    </div>
+  );
+}

package/src/components/pagination/examples/states.tsx

@@ -0,0 +1,80 @@
+import { Pagination } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Previous disabled on first page, next on last; both disabled when `totalPages` is 1.
+ * Parity with `playground/snippets/pagination/states.tsx`.
+ */
+export default function PaginationStatesExample() {
+  const [first, setFirst] = React.useState(1);
+  const [last, setLast] = React.useState(10);
+  const [single, setSingle] = React.useState(1);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-x4)",
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: "var(--prime-sys-spacing-x2)",
+          alignItems: "flex-start",
+        }}
+      >
+        <p
+          style={{
+            margin: 0,
+            fontSize: "var(--prime-sys-size-control-s-supportText)",
+            color: "var(--prime-sys-color-content-secondary)",
+          }}
+        >
+          First of ten
+        </p>
+        <Pagination.Root page={first} totalPages={10} onPageChange={setFirst} />
+      </div>
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: "var(--prime-sys-spacing-x2)",
+          alignItems: "flex-start",
+        }}
+      >
+        <p
+          style={{
+            margin: 0,
+            fontSize: "var(--prime-sys-size-control-s-supportText)",
+            color: "var(--prime-sys-color-content-secondary)",
+          }}
+        >
+          Last of ten
+        </p>
+        <Pagination.Root page={last} totalPages={10} onPageChange={setLast} />
+      </div>
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: "var(--prime-sys-spacing-x2)",
+          alignItems: "flex-start",
+        }}
+      >
+        <p
+          style={{
+            margin: 0,
+            fontSize: "var(--prime-sys-size-control-s-supportText)",
+            color: "var(--prime-sys-color-content-secondary)",
+          }}
+        >
+          Single page
+        </p>
+        <Pagination.Root page={single} totalPages={1} onPageChange={setSingle} />
+      </div>
+    </div>
+  );
+}

package/src/components/popover/COMPONENT.md

@@ -40,57 +40,46 @@ export function Example() {
 
 ### Canonical panel (reference)
 
-Typical English recipe: stroke **`Button.Root`** trigger, **`insetPadding` / `insetGap`**, and short body copy. Source of truth (stays in sync with the snippet mindset below): **`examples/canonical-panel.tsx`**.
+Short English recipe (stroke trigger, **`insetPadding` / `insetGap`**, body copy): **`examples/canonical-panel.tsx`**.
 
-```tsx
-import { Button, Popover, Typography } from "prime-ui-kit";
+### Playground-aligned examples
 
-export function ShippingEstimatePopover() {
-  return (
-    <Popover.Root>
-      <Popover.Trigger asChild>
-        <Button.Root mode="stroke" size="m" variant="neutral">
-          View details
-        </Button.Root>
-      </Popover.Trigger>
-      <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom" size="m">
-        <Typography.Root as="p" variant="body-small" weight="semibold">
-          Shipping estimate
-        </Typography.Root>
-        <Typography.Root as="p" variant="body-small">
-          Arrives Tuesday–Thursday for metro addresses. Rural routes may add one business day.
-        </Typography.Root>
-      </Popover.Content>
-    </Popover.Root>
-  );
-}
-```
+**`playground/sections/PopoverSection.tsx`** and **`playground/snippets/popover/`** define the demo order and code shown in the playground (Russian UI copy). Matching runnable package examples (imports from **`"prime-ui-kit"`**) live next to this file:
+
+| Playground block | Snippet | Example file |
+|------------------|---------|--------------|
+| Sizes | `sizes.tsx` | `sizes.tsx` |
+| Inset variants | `inset-variants.tsx` | `inset-variants.tsx` |
+| States | `states.tsx` | `states.tsx` |
+| Placement | `placement.tsx` | `placement.tsx` |
+| Controlled | `controlled.tsx` | `controlled.tsx` |
+| Composition | `composition.tsx` | `composition.tsx` |
+| Full width (trigger) | `full-width.tsx` | `full-width.tsx` |
+| Custom trigger | `as-child.tsx` | `as-child.tsx` |
+| Focus + nested Select | `features.tsx` | `features.tsx` |
 
-### Example files in `examples/`
+Shared layout for these examples: **`examples/popover-examples.module.css`**.
 
-Runnable demos live next to this file. Imports use **`"prime-ui-kit"`** so the same snippets work in an app after installing the package.
+### Additional examples in `examples/`
 
 | File | Intent |
 |------|--------|
-| `canonical-panel.tsx` | Default composition: stroke trigger, inset spacing, short copy |
+| `canonical-panel.tsx` | Default English composition: stroke trigger, inset spacing, short copy |
 | `date-trigger.tsx` | Date-style trigger label; native **`type="date"`** field; **`trapFocus`** |
 | `rich-content.tsx` | Badges, **`Divider`**, **`Hint`** — denser non-modal panel |
-| `placement.tsx` | **`side`** and **`align`** grid; flip behavior called out in copy |
 | `form-in-popover.tsx` | Controlled root, small form, **`trapFocus`**, submit closes |
 
-Broader Russian demos and layout variants: **`playground/snippets/popover/`** (for example `composition.tsx`, `placement.tsx`, `controlled.tsx`).
-
 ### Extended usage
 
 - **Controlled popovers:** pass **`open`** and **`onOpenChange`** on **`Popover.Root`**; keep **`Popover.Trigger`** and **`Popover.Content`** as siblings. Close from inside the panel by calling the same setter or relying on outside click / Escape.
-- **Forms and focus:** set **`trapFocus={true}`** on **`Popover.Content`** when several controls should keep Tab cycles inside the panel (see **`examples/form-in-popover.tsx`** and **`examples/date-trigger.tsx`**).
-- **Match trigger width:** use **`sameMinWidthAsTrigger`** when the panel should align visually with a full-width or fixed-width anchor (still bounded by max width and viewport).
-- **Nested Select:** portaled Select listbox clicks owned by the panel are not treated as outside closes (see `isPortaledSelectListboxOwnedByContainer` in implementation).
+- **Forms and focus:** set **`trapFocus={true}`** on **`Popover.Content`** when several controls should keep Tab cycles inside the panel (see **`examples/form-in-popover.tsx`**, **`examples/date-trigger.tsx`**, and **`examples/features.tsx`**).
+- **Match trigger width:** use **`sameMinWidthAsTrigger`** when the panel should match the trigger’s **`width`** and **`minWidth`** (`border-box`, text wraps; still bounded by panel max width and viewport). See **`examples/full-width.tsx`**.
+- **Nested Select:** portaled Select listbox clicks owned by the panel are not treated as outside closes (see `isPortaledSelectListboxOwnedByContainer` in implementation; **`examples/features.tsx`**).
 - **Density:** tune **`size`** on **`Popover.Content`** for nested controls and **`insetPadding` / `insetGap`** for internal vertical rhythm; optional **`className`** on **`Content`** for scoped layout hooks.
 
 ### Note for LLMs
 
-When generating **Popover** markup for this library: (1) **`Popover.Trigger`** accepts **exactly one** child element—no fragments or multiple nodes. (2) Prefer **`Button.Root`**, **`LinkButton.Root`**, or another kit control as the trigger so sizing and focus styles stay on the design-system tier. (3) Only **`side="top"`** and **`side="bottom"`** are valid; do not assume left/right anchoring. (4) For copy-paste starting points, mirror **`examples/canonical-panel.tsx`**, then adapt **`date-trigger.tsx`**, **`rich-content.tsx`**, **`placement.tsx`**, or **`form-in-popover.tsx`**. (5) Do not wrap kit components to restyle them; use **`size`**, **`variant`**, **`mode`**, **`insetPadding`**, **`insetGap`**, and documented props only.
+When generating **Popover** markup for this library: (1) **`Popover.Trigger`** accepts **exactly one** child element—no fragments or multiple nodes. (2) Prefer **`Button.Root`**, **`LinkButton.Root`**, or another kit control as the trigger so sizing and focus styles stay on the design-system tier. (3) Only **`side="top"`** and **`side="bottom"`** are valid; do not assume left/right anchoring. (4) Align scenarios with **`playground/snippets/popover/`** and the matching **`examples/*.tsx`** files in the table above; add **`canonical-panel.tsx`**, **`date-trigger.tsx`**, **`rich-content.tsx`**, or **`form-in-popover.tsx`** when you need those extra recipes. (5) Do not wrap kit components to restyle them; use **`size`**, **`variant`**, **`mode`**, **`insetPadding`**, **`insetGap`**, and documented props only.
 
 ## Rules
 
@@ -129,7 +118,7 @@ When generating **Popover** markup for this library: (1) **`Popover.Trigger`** a
 |------|------|---------|----------|-------------|
 | align | `"start" \| "center" \| "end"` | `"start"` | No | Horizontal alignment of the panel relative to the trigger. |
 | side | `"bottom" \| "top"` | `"bottom"` | No | Preferred side; layout may flip at the viewport edge. |
-| sameMinWidthAsTrigger | `boolean` | `false` | No | Panel min width matches the trigger (`border-box`), still subject to panel max width and viewport. |
+| sameMinWidthAsTrigger | `boolean` | `false` | No | When `true`, panel `width` and `minWidth` match the trigger (`border-box`); text wraps; still subject to panel max width and viewport. |
 | size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Control density tier for nested controls via `ControlSizeProvider`. |
 | trapFocus | `boolean` | `false` | No | Trap focus inside the panel while open. |
 | insetPadding | `"none" \| "x1" \| "x2" \| "x3"` | `"none"` | No | Extra inset padding relative to the panel tier (`data-inset-padding`). |

package/src/components/popover/examples/as-child.tsx

@@ -0,0 +1,24 @@
+import { Popover } from "prime-ui-kit";
+
+import styles from "./popover-examples.module.css";
+
+/**
+ * Single custom child under `Popover.Trigger` (native `<button>` styled as a text link): ref and ARIA merge on that element.
+ */
+export default function PopoverAsChildExample() {
+  return (
+    <Popover.Root>
+      <Popover.Trigger asChild>
+        <button className={styles.textLinkTrigger} type="button">
+          Text button trigger
+        </button>
+      </Popover.Trigger>
+      <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom" size="m">
+        <p className={styles.panelTextMuted}>
+          One arbitrary element as the anchor; the kit merges <code>ref</code>,{" "}
+          <code>aria-expanded</code>, <code>aria-controls</code>, and the click toggle handler.
+        </p>
+      </Popover.Content>
+    </Popover.Root>
+  );
+}