prime-ui-kit 0.0.1

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/pagination/examples/table-footer.tsx

@@ -0,0 +1,74 @@
+import { Pagination } from "prime-ui-kit";
+import * as React from "react";
+
+const PAGE_SIZE = 10;
+const TOTAL_ROWS = 247;
+
+function rangeLabel(page: number, pageSize: number, total: number) {
+  const start = (page - 1) * pageSize + 1;
+  const end = Math.min(page * pageSize, total);
+  return `Showing ${start}–${end} of ${total}`;
+}
+
+/** Table-style footer: row summary plus Pagination.Root aligned on one row. */
+export default function TableFooterExample() {
+  const [page, setPage] = React.useState(1);
+  const totalPages = Math.max(1, Math.ceil(TOTAL_ROWS / PAGE_SIZE));
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        borderRadius: "var(--prime-sys-radius-m)",
+        border: "1px solid var(--prime-sys-color-border-subtle)",
+        background: "var(--prime-sys-color-surface-raised)",
+        overflow: "hidden",
+        maxWidth: "42rem",
+      }}
+    >
+      <div
+        style={{
+          padding: "var(--prime-sys-spacing-x3) var(--prime-sys-spacing-x4)",
+          borderBottom: "1px solid var(--prime-sys-color-border-subtle)",
+          fontSize: "var(--prime-sys-size-control-s-supportText)",
+          color: "var(--prime-sys-color-content-secondary)",
+        }}
+      >
+        Sample rows (page {page} of {totalPages})
+      </div>
+      <div
+        style={{
+          padding: "var(--prime-sys-spacing-x4)",
+          minHeight: "6rem",
+          color: "var(--prime-sys-color-content-muted)",
+          fontSize: "var(--prime-sys-size-control-s-supportText)",
+        }}
+      >
+        …
+      </div>
+      <div
+        style={{
+          display: "flex",
+          flexWrap: "wrap",
+          alignItems: "center",
+          justifyContent: "space-between",
+          gap: "var(--prime-sys-spacing-x3)",
+          padding: "var(--prime-sys-spacing-x3) var(--prime-sys-spacing-x4)",
+          borderTop: "1px solid var(--prime-sys-color-border-subtle)",
+        }}
+      >
+        <span
+          style={{
+            fontSize: "var(--prime-sys-size-control-s-supportText)",
+            color: "var(--prime-sys-color-content-secondary)",
+            lineHeight: "var(--prime-sys-typography-body-lineHeight)",
+          }}
+        >
+          {rangeLabel(page, PAGE_SIZE, TOTAL_ROWS)}
+        </span>
+        <Pagination.Root page={page} totalPages={totalPages} onPageChange={setPage} />
+      </div>
+    </div>
+  );
+}

package/src/components/popover/COMPONENT.md

@@ -0,0 +1,146 @@
+# Popover
+
+**Default sizing:** when designing screens and examples, start with **`m`** for `size` (where a size axis exists) unless the scenario explicitly needs another value.
+
+## About
+
+A composite “anchor + portaled panel”: clicking the trigger toggles a non-modal dialog next to the anchor, positioned toward the viewport edge and dismissible with Escape or an outside click.
+
+- **Use** for short contextual panels—help text, compact filters, a few fields or actions—without leaving the page or blocking the whole UI.
+- **Use** when content should stay visually tied to a specific control (metrics, footnotes, inline configuration).
+- **Do not use** for full-screen or blocking flows; prefer [Modal](../modal/COMPONENT.md).
+- **Do not use** for hover-only hints; prefer [Tooltip](../tooltip/COMPONENT.md).
+- **Do not use** expecting left/right placement relative to the anchor; only **top** and **bottom** sides are supported.
+- **Do not use** with multiple or fragment children under `Popover.Trigger`; exactly **one** element is supported.
+
+## Composition
+
+- **`Popover.Root`** — holds open state (controlled or uncontrolled), stable ids for trigger and content, and the trigger element ref used for positioning.
+- **`Popover.Trigger`** — must wrap **exactly one** `React` element; ref, `aria-*`, and click-to-toggle are merged onto that child (`cloneElement`).
+- **`Popover.Content`** — rendered in a **portal** only when open; root is a scroll container with `role="dialog"`, positioned from the trigger via `side` / `align`, wraps children in `ControlSizeProvider` when `size` is set, and applies optional **`insetPadding`** / **`insetGap`** on the same node (`data-inset-padding`, `data-inset-gap`).
+
+### Minimal example
+
+```tsx
+import { Button, Popover } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Popover.Root>
+      <Popover.Trigger asChild>
+        <Button.Root type="button">Open</Button.Root>
+      </Popover.Trigger>
+      <Popover.Content>
+        Panel
+      </Popover.Content>
+    </Popover.Root>
+  );
+}
+```
+
+### Canonical panel (reference)
+
+Short English recipe (stroke trigger, **`insetPadding` / `insetGap`**, body copy): **`examples/canonical-panel.tsx`**.
+
+### Playground-aligned examples
+
+**`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` |
+
+Shared layout for these examples: **`examples/popover-examples.module.css`**.
+
+### Additional examples in `examples/`
+
+| File | Intent |
+|------|--------|
+| `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 |
+| `form-in-popover.tsx` | Controlled root, small form, **`trapFocus`**, submit closes |
+
+### 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`**, **`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) 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
+
+- **Uncontrolled:** use `defaultOpen` on `Popover.Root` for the initial open state after mount.
+- **Controlled:** pass `open` and `onOpenChange` together; parent can open or close from outside logic.
+- When closed, **`Popover.Content`** returns `null` (nothing is mounted in the portal).
+- **`trapFocus`** on `Popover.Content` keeps Tab cycling inside the panel while open and restores focus on close when enabled.
+- **Escape** and **outside click** call close; clicks on a portaled **Select** listbox that belongs to the panel are ignored as outside (see `isPortaledSelectListboxOwnedByContainer`).
+- **Non-modal:** `aria-modal={false}`—focus can leave the page; this is intentional for a lightweight overlay.
+- Trigger receives **`aria-expanded`**, **`aria-haspopup="dialog"`**, and **`aria-controls`** pointing at the content id; **`aria-labelledby`** on the panel references the trigger id—give the anchor a visible name or **`aria-label`** when there is no text.
+- There is no popover-level **`disabled`**; if the anchor (e.g. [Button](../button/COMPONENT.md)) is disabled, it will not open.
+- **`asChild`** exists for slot API compatibility; merging always applies to the single child—**`asChild={false}`** does not render an internal button.
+- Density: tune **`Popover.Content` `size`** for the control tier and **`insetPadding` / `insetGap`** for inner spacing; optional **`className`** on `Content` for further styling.
+
+## API
+
+### Popover.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| open | `boolean` | — | No | Controlled open state; use with `onOpenChange`. |
+| defaultOpen | `boolean` | `false` | No | Initial state in uncontrolled mode. |
+| onOpenChange | `(open: boolean) => void` | — | No | Fires when opening or closing (trigger, Escape, outside click). |
+| children | `React.ReactNode` | — | Yes | Typically `Popover.Trigger` and `Popover.Content`. |
+
+### Popover.Trigger
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactElement` | — | Yes | Single anchor element; ref, ARIA, and click handler are merged in. |
+| asChild | `boolean` | `true` | No | Reserved for slot API compatibility; behavior always merges with the single child. |
+
+### Popover.Content
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| 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 | 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`). |
+| insetGap | `"none" \| "x2" \| "x3" \| "x4"` | `"none"` | No | Vertical gap between direct children (`data-inset-gap`). |
+| className | `string` | — | No | Extra class on the panel root. |
+| children | `React.ReactNode` | — | Yes | Panel body. |
+
+## Related
+
+- [Button](../button/COMPONENT.md), [LinkButton](../link-button/COMPONENT.md) — typical triggers.
+- [Select](../select/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md) — nested overlays; Select listbox clicks are treated as inside the popover when owned by the panel.
+- [Input](../input/COMPONENT.md), [Textarea](../textarea/COMPONENT.md), [Checkbox](../checkbox/COMPONENT.md), [Switch](../switch/COMPONENT.md) — fields inside the panel.
+- [Typography](../typography/COMPONENT.md), [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md) — text and labels in the panel.
+- [Badge](../badge/COMPONENT.md), [Divider](../divider/COMPONENT.md) — structured panel chrome.
+- [Modal](../modal/COMPONENT.md) — blocking modal flow.
+- [Tooltip](../tooltip/COMPONENT.md) — short hover/focus hint without an action panel.
+
+</think>
+<think>
+I made a mistake in Related - Switch should link to COMPONENT.md not Switch.tsx
+</think>
+
+
+<｜tool▁calls▁begin｜><｜tool▁call▁begin｜>
+Glob

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" side="bottom">
+        <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>
+  );
+}

package/src/components/popover/examples/canonical-panel.tsx

@@ -0,0 +1,24 @@
+import { Button, Popover, Typography } from "prime-ui-kit";
+
+/**
+ * Canonical panel: stroke trigger, inset spacing, and a short description inside the portaled surface.
+ */
+export default function CanonicalPanelExample() {
+  return (
+    <Popover.Root>
+      <Popover.Trigger asChild>
+        <Button.Root mode="stroke" variant="neutral">
+          View details
+        </Button.Root>
+      </Popover.Trigger>
+      <Popover.Content align="start" side="bottom">
+        <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>
+  );
+}

package/src/components/popover/examples/composition.tsx

@@ -0,0 +1,42 @@
+import { Filter, SlidersHorizontal } from "lucide-react";
+import { Button, Checkbox, Popover, Typography } from "prime-ui-kit";
+
+import styles from "./popover-examples.module.css";
+
+/**
+ * Trigger with `Button.Icon`, header row, body copy, and native checkboxes with panel padding from `Content` `size`.
+ */
+export default function PopoverCompositionExample() {
+  return (
+    <Popover.Root>
+      <Popover.Trigger asChild>
+        <Button.Root mode="stroke" variant="neutral">
+          <Button.Icon>
+            <SlidersHorizontal aria-hidden strokeWidth={1.75} />
+          </Button.Icon>
+          Report filters
+        </Button.Root>
+      </Popover.Trigger>
+      <Popover.Content align="start" side="bottom">
+        <div className={styles.compositionHeader}>
+          <Filter aria-hidden className={styles.headerIcon} strokeWidth={1.75} />
+          <Typography.Root as="span" variant="body-small" weight="semibold">
+            Quick filters
+          </Typography.Root>
+        </div>
+        <Typography.Root as="p" className={styles.panelTextMuted} variant="body-small">
+          Icon on the trigger, header and copy; panel padding comes from <code>Content</code>{" "}
+          <code>size</code>.
+        </Typography.Root>
+        <div className={styles.checkboxStack}>
+          <Checkbox.Root defaultChecked>
+            <Checkbox.Label>Active only</Checkbox.Label>
+          </Checkbox.Root>
+          <Checkbox.Root>
+            <Checkbox.Label>Hide zero values</Checkbox.Label>
+          </Checkbox.Root>
+        </div>
+      </Popover.Content>
+    </Popover.Root>
+  );
+}

package/src/components/popover/examples/controlled.tsx

@@ -0,0 +1,40 @@
+import { Button, Popover, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./popover-examples.module.css";
+
+/**
+ * Controlled `open` / `onOpenChange` on `Popover.Root`: open from outside, toggle from trigger, close from panel.
+ */
+export default function PopoverControlledExample() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <div className={styles.controlledRow}>
+      <Typography.Root as="p" className={styles.stateLine} variant="body-small" weight="medium">
+        Panel is {open ? "open" : "closed"}
+      </Typography.Root>
+      <div className={styles.sizesRow}>
+        <Button.Root mode="stroke" variant="neutral" onClick={() => setOpen(true)}>
+          Open from outside
+        </Button.Root>
+        <Popover.Root open={open} onOpenChange={setOpen}>
+          <Popover.Trigger asChild>
+            <Button.Root mode="filled" variant="primary">
+              Toggle with trigger
+            </Button.Root>
+          </Popover.Trigger>
+          <Popover.Content align="start" side="bottom">
+            <p className={styles.panelTextMuted}>
+              State is driven by <code>open</code> and <code>onOpenChange</code> on{" "}
+              <code>Popover.Root</code>.
+            </p>
+            <Button.Root mode="ghost" variant="neutral" onClick={() => setOpen(false)}>
+              Close
+            </Button.Root>
+          </Popover.Content>
+        </Popover.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/popover/examples/date-trigger.tsx

@@ -0,0 +1,26 @@
+import { Button, Input, Popover, Typography } from "prime-ui-kit";
+
+/**
+ * Date-oriented trigger: formatted label on the anchor, native date input inside the panel.
+ */
+export default function DateTriggerExample() {
+  return (
+    <Popover.Root>
+      <Popover.Trigger asChild>
+        <Button.Root aria-label="Choose due date" mode="stroke" variant="neutral">
+          Due · Mar 27, 2025
+        </Button.Root>
+      </Popover.Trigger>
+      <Popover.Content align="start" side="bottom" trapFocus>
+        <Typography.Root as="p" variant="body-small" weight="semibold">
+          Adjust due date
+        </Typography.Root>
+        <Input.Root hint="Uses the control size from Popover.Content." label="Due date">
+          <Input.Wrapper>
+            <Input.Field defaultValue="2025-03-27" name="dueDate" type="date" />
+          </Input.Wrapper>
+        </Input.Root>
+      </Popover.Content>
+    </Popover.Root>
+  );
+}

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

@@ -0,0 +1,58 @@
+import { Button, Input, Popover, Select, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./popover-examples.module.css";
+
+/**
+ * `trapFocus` with `Input` and nested `Select`: portaled listbox clicks are not treated as outside close.
+ */
+export default function PopoverFeaturesExample() {
+  const [open, setOpen] = React.useState(false);
+  const [name, setName] = React.useState("");
+
+  return (
+    <Popover.Root open={open} onOpenChange={setOpen}>
+      <Popover.Trigger asChild>
+        <Button.Root className={styles.triggerWide} mode="stroke" variant="neutral">
+          Access request
+        </Button.Root>
+      </Popover.Trigger>
+      <Popover.Content align="start" className={styles.formPanel} sameMinWidthAsTrigger trapFocus>
+        <Typography.Root as="p" variant="body-small" weight="medium">
+          Short form
+        </Typography.Root>
+        <Typography.Root as="p" className={styles.panelTextMuted} variant="body-small">
+          <code>trapFocus</code> keeps Tab inside the panel; opening the Select listbox does not
+          count as an outside click, so the popover stays open.
+        </Typography.Root>
+        <Input.Root label="Comment">
+          <Input.Wrapper>
+            <Input.Field
+              placeholder="Why access is needed"
+              value={name}
+              onChange={(e) => setName(e.target.value)}
+            />
+          </Input.Wrapper>
+        </Input.Root>
+        <Select.Root placeholder="Role">
+          <Select.Trigger>
+            <Select.Value />
+          </Select.Trigger>
+          <Select.Content>
+            <Select.Item value="viewer">Viewer</Select.Item>
+            <Select.Item value="editor">Editor</Select.Item>
+            <Select.Item value="admin">Admin</Select.Item>
+          </Select.Content>
+        </Select.Root>
+        <div className={styles.actionsRow}>
+          <Button.Root mode="ghost" variant="neutral" onClick={() => setOpen(false)}>
+            Cancel
+          </Button.Root>
+          <Button.Root mode="filled" variant="primary" onClick={() => setOpen(false)}>
+            Submit
+          </Button.Root>
+        </div>
+      </Popover.Content>
+    </Popover.Root>
+  );
+}

package/src/components/popover/examples/form-in-popover.tsx

@@ -0,0 +1,71 @@
+import { Button, Input, Popover, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Short form inside the panel: enable trapFocus when multiple fields need a tight tab cycle.
+ */
+export default function FormInPopoverExample() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <Popover.Root open={open} onOpenChange={setOpen}>
+      <Popover.Trigger asChild>
+        <Button.Root mode="stroke" variant="neutral">
+          Quick edit
+        </Button.Root>
+      </Popover.Trigger>
+      <Popover.Content align="start" side="bottom" trapFocus>
+        <form
+          style={{ width: "min(22rem, 100vw)" }}
+          onSubmit={(e) => {
+            e.preventDefault();
+            setOpen(false);
+          }}
+        >
+          <Typography.Root as="p" variant="body-small" weight="semibold">
+            Workspace label
+          </Typography.Root>
+          <div
+            style={{
+              display: "flex",
+              flexDirection: "column",
+              gap: "var(--prime-sys-spacing-x3)",
+              marginTop: "var(--prime-sys-spacing-x2)",
+            }}
+          >
+            <Input.Root label="Display name">
+              <Input.Wrapper>
+                <Input.Field autoComplete="organization" name="displayName" type="text" />
+              </Input.Wrapper>
+            </Input.Root>
+            <Input.Root label="Slug" hint="Lowercase, no spaces.">
+              <Input.Wrapper>
+                <Input.Field name="slug" type="text" />
+              </Input.Wrapper>
+            </Input.Root>
+          </div>
+          <div
+            style={{
+              display: "flex",
+              justifyContent: "flex-end",
+              gap: "var(--prime-sys-spacing-x2)",
+              marginTop: "var(--prime-sys-spacing-x3)",
+            }}
+          >
+            <Button.Root
+              mode="stroke"
+              type="button"
+              variant="neutral"
+              onClick={() => setOpen(false)}
+            >
+              Cancel
+            </Button.Root>
+            <Button.Root type="submit" variant="primary">
+              Save
+            </Button.Root>
+          </div>
+        </form>
+      </Popover.Content>
+    </Popover.Root>
+  );
+}

package/src/components/popover/examples/full-width.tsx

@@ -0,0 +1,27 @@
+import { Button, Popover } from "prime-ui-kit";
+
+import styles from "./popover-examples.module.css";
+
+/**
+ * `sameMinWidthAsTrigger`: panel width matches the trigger (`border-box`), useful in narrow columns.
+ */
+export default function PopoverFullWidthExample() {
+  return (
+    <div className={styles.narrowColumn}>
+      <Popover.Root>
+        <Popover.Trigger asChild>
+          <Button.Root className={styles.fullWidthTrigger} mode="stroke" variant="neutral">
+            Match trigger width
+          </Button.Root>
+        </Popover.Trigger>
+        <Popover.Content align="start" sameMinWidthAsTrigger side="bottom">
+          <p className={styles.panelTextMuted}>
+            <code>sameMinWidthAsTrigger</code> sets panel <code>width</code> and{" "}
+            <code>minWidth</code> to the anchor — text wraps, still capped by panel max width and
+            the viewport.
+          </p>
+        </Popover.Content>
+      </Popover.Root>
+    </div>
+  );
+}