@cruglobal/cornerstone-components 0.1.0

package/dist/bundled/skills/cornerstone/references/components/pagination.md

@@ -0,0 +1,466 @@
+# Pagination
+
+**Full documentation:** https://cruglobal.github.io/cornerstone-design-system/components/pagination
+
+```html
+<cs-pagination total="237" page-size="10" page="3" label="Search results"></cs-pagination>
+```
+
+Set `total` and `page-size` to generate numbered page buttons with previous and next controls. Use the `label` attribute to give the control an accessible name, which is especially helpful when more than one appears on the same page.
+
+> **Info**
+>
+> <strong>Pagination is a navigation control, not a form control.</strong><br />
+> It tracks the current page and emits events, but it doesn't submit a value with a form. Keep `page` in sync with your data by updating it in response to the [`cs-after-page-change`](#responding-to-page-changes) event.
+
+## Examples
+
+### Appearance
+
+Set the `appearance` attribute to change the pagination's visual style. Valid appearances are `outlined` (the default), `filled`, and `plain`.
+
+```html
+<div class="cs-stack">
+  <cs-pagination total="237" page-size="10" page="3" appearance="outlined"></cs-pagination>
+  <cs-pagination total="237" page-size="10" page="3" appearance="filled"></cs-pagination>
+  <cs-pagination total="237" page-size="10" page="3" appearance="plain"></cs-pagination>
+</div>
+```
+
+### Size
+
+Pagination has no `size` attribute; set `font-size` on the control or any ancestor to scale it.
+
+```html
+<div class="cs-stack">
+  <cs-pagination total="237" page-size="10" page="3" style="font-size: var(--cs-font-size-s)"></cs-pagination>
+  <cs-pagination total="237" page-size="10" page="3"></cs-pagination>
+  <cs-pagination total="237" page-size="10" page="3" style="font-size: var(--cs-font-size-l)"></cs-pagination>
+</div>
+```
+
+### Number of Buttons
+
+Use the `sibling-count` attribute to set how many pages show on each side of the current page (defaults to `2`), and `boundary-count` to set how many show at the start and end (defaults to `1`). Remaining pages collapse into an ellipsis, which jumps several pages toward that side when activated.
+
+```html
+<div class="cs-stack">
+  <cs-pagination total="1000" page-size="10" page="50" sibling-count="1" boundary-count="1"></cs-pagination>
+  <cs-pagination total="1000" page-size="10" page="50" sibling-count="3" boundary-count="2"></cs-pagination>
+</div>
+```
+
+### First and Last Buttons
+
+Add the `with-edges` attribute to show buttons that jump to the first and last pages.
+
+```html
+<cs-pagination total="237" page-size="10" page="10" with-edges></cs-pagination>
+```
+
+### Previous and Next Buttons
+
+Add the `without-nav` attribute to hide the previous and next buttons, leaving only the page numbers.
+
+```html
+<cs-pagination total="237" page-size="10" page="3" without-nav></cs-pagination>
+```
+
+### Summary
+
+Add the `with-summary` attribute to show a summary of the items on the current page.
+
+```html
+<cs-pagination total="237" page-size="10" page="1" with-summary></cs-pagination>
+```
+
+### Compact
+
+Set the `format` attribute to `compact` to replace the page numbers with a short "1 of 5" label between the previous and next buttons.
+
+```html
+<cs-pagination total="237" page-size="10" page="1" format="compact"></cs-pagination>
+```
+
+The compact format can be combined with other features, such as `with-summary`:
+
+```html
+<cs-pagination total="237" page-size="10" page="1" format="compact" with-summary></cs-pagination>
+```
+
+### Custom Icons
+
+Use the `previous-icon`, `next-icon`, `first-icon`, and `last-icon` slots to replace the default navigation icons.
+
+```html
+<cs-pagination total="237" page-size="10" page="5" with-edges>
+  <cs-icon slot="previous-icon" name="skip_previous" variant="fill"></cs-icon>
+  <cs-icon slot="next-icon" name="skip_next" variant="fill"></cs-icon>
+  <cs-icon slot="first-icon" name="first_page"></cs-icon>
+  <cs-icon slot="last-icon" name="last_page"></cs-icon>
+</cs-pagination>
+```
+
+> **Info**
+>
+> <strong>Replacing an icon doesn't replace its label.</strong><br />
+> The navigation buttons keep their built-in accessible labels, so screen readers still announce them correctly.
+
+### Disabled
+
+Add the `disabled` attribute to disable the entire pagination control.
+
+```html
+<cs-pagination total="237" page-size="10" page="3" disabled></cs-pagination>
+```
+
+### Single Page
+
+Add the `hide-single-page` attribute to render nothing when there's only one page of results. Since a single page renders nothing, this example is shown as code rather than a live preview.
+
+```html
+<cs-pagination total="5" page-size="10" hide-single-page></cs-pagination>
+```
+
+### Page Size Selector
+
+Pair a [select](https://cruglobal.github.io/cornerstone-design-system/components/select) with the pagination control to let users change the page size. Update `page-size` when the selection changes, and reset to the first page.
+
+```html
+<div class="pagination-page-size">
+  <cs-pagination total="237" page-size="10" page="1"></cs-pagination>
+
+  <cs-select label="Items per page" value="10" size="s">
+    <cs-option value="10">10</cs-option>
+    <cs-option value="20">20</cs-option>
+    <cs-option value="50">50</cs-option>
+    <cs-option value="100">100</cs-option>
+  </cs-select>
+</div>
+
+<style>
+  .pagination-page-size {
+    display: flex;
+    align-items: end;
+    gap: var(--cs-space-l);
+    flex-wrap: wrap;
+  }
+
+  .pagination-page-size cs-select {
+    inline-size: 8rem;
+  }
+</style>
+
+<script type="module">
+  const container = document.querySelector('.pagination-page-size');
+  const pagination = container.querySelector('cs-pagination');
+  const select = container.querySelector('cs-select');
+
+  select.addEventListener('change', () => {
+    pagination.pageSize = Number(select.value);
+    pagination.page = 1;
+  });
+</script>
+```
+
+### Responding to Page Changes
+
+When the user changes the page, the `cs-after-page-change` event is emitted with `{ page, pageSize }` in `event.detail`. Update the `page` property to reflect the new page and load the corresponding data.
+
+```html
+<div class="pagination-change-demo">
+  <cs-pagination class="pagination-change" total="237" page-size="10" page="1"></cs-pagination>
+
+  <cs-divider></cs-divider>
+
+  <small class="pagination-change-output" style="display: block">Showing page 1</small>
+</div>
+
+<script type="module">
+  const container = document.querySelector('.pagination-change-demo');
+  const pagination = container.querySelector('.pagination-change');
+  const output = container.querySelector('.pagination-change-output');
+
+  pagination.addEventListener('cs-after-page-change', event => {
+    pagination.page = event.detail.page;
+    output.textContent = `Showing page ${event.detail.page}`;
+  });
+</script>
+```
+
+### Setting the Page Programmatically
+
+Set the `page` property to any valid page to change the current page without user interaction. Setting `page` directly doesn't emit `cs-after-page-change`.
+
+```html
+<div class="pagination-set-demo">
+  <cs-pagination class="pagination-set" total="237" page-size="10" page="1"></cs-pagination>
+
+  <cs-divider></cs-divider>
+
+  <div class="cs-cluster">
+    <cs-button appearance="filled" data-page="1">Page 1</cs-button>
+    <cs-button appearance="filled" data-page="5">Page 5</cs-button>
+    <cs-button appearance="filled" data-page="10">Page 10</cs-button>
+  </div>
+</div>
+
+<script type="module">
+  const container = document.querySelector('.pagination-set-demo');
+  const pagination = container.querySelector('.pagination-set');
+
+  container.querySelectorAll('[data-page]').forEach(button => {
+    button.addEventListener('click', () => {
+      pagination.page = Number(button.dataset.page);
+    });
+  });
+</script>
+```
+
+### Preventing a Page Change
+
+Call `event.preventDefault()` on the `cs-page-change` event to cancel a page change, such as to guard against unsaved changes.
+
+```html
+<cs-pagination class="pagination-guard" total="237" page-size="10" page="1"></cs-pagination>
+
+<script type="module">
+  const pagination = document.querySelector('.pagination-guard');
+
+  pagination.addEventListener('cs-page-change', event => {
+    if (!window.confirm(`Leave for page ${event.detail.page}?`)) {
+      event.preventDefault();
+    }
+  });
+
+  pagination.addEventListener('cs-after-page-change', event => {
+    pagination.page = event.detail.page;
+  });
+</script>
+```
+
+### Rendering Links Instead of Buttons
+
+Set the `href-template` attribute to render page items as links instead of buttons, using `{page}` as a placeholder for the page number. Every control links through the template, which works well for server-rendered pages.
+
+```html
+<cs-pagination total="237" page-size="10" page="3" href-template="?page={page}"></cs-pagination>
+```
+
+In JavaScript, you can also set the `hrefTemplate` property to a function that receives the page number and returns the URL. This is handy when the URL doesn't follow a simple substitution. When server-rendering, set the `href-template` attribute to the closest equivalent as well, so the server and the browser render the same markup.
+
+```html
+<cs-pagination
+  class="pagination-href-fn"
+  total="237"
+  page-size="10"
+  page="3"
+  href-template="?page={page}#results"
+></cs-pagination>
+
+<script type="module">
+  const pagination = document.querySelector('.pagination-href-fn');
+
+  pagination.hrefTemplate = page => `?page=${page}#results`;
+</script>
+```
+
+> **Info**
+>
+> <strong>In link mode, the component navigates instead of updating itself.</strong><br />
+> Render it on the server with the correct `page` for each request. Disabled and boundary controls, such as previous on the first page, render as anchors with no `href` and `aria-disabled` set.
+
+### Customizing
+
+Use the exported [CSS parts](#css-parts) to customize the pagination's appearance, where the `button` part targets every button at once. The `plain` appearance is a good starting point.
+
+This example turns the control into a row of pill-shaped buttons, gives the navigation arrows a colorful circular treatment, and highlights the current page with a gradient and a soft glow.
+
+```html
+<cs-pagination
+  class="custom-pagination"
+  total="237"
+  page-size="10"
+  page="3"
+  appearance="plain"
+  with-edges
+  sibling-count="1"
+>
+  <cs-icon slot="previous-icon" name="keyboard_arrow_left"></cs-icon>
+  <cs-icon slot="next-icon" name="keyboard_arrow_right"></cs-icon>
+  <cs-icon slot="first-icon" name="keyboard_double_arrow_left"></cs-icon>
+  <cs-icon slot="last-icon" name="keyboard_double_arrow_right"></cs-icon>
+</cs-pagination>
+
+<style>
+  .custom-pagination {
+    --gradient: linear-gradient(135deg, var(--cs-color-brand-fill-loud), var(--cs-color-purple-50));
+  }
+
+  /* The host uses `display: contents`, so style the `pagination` part to create the container chrome. */
+  .custom-pagination::part(pagination) {
+    padding: var(--cs-space-xs);
+    border-radius: var(--cs-border-radius-pill);
+    background-color: var(--cs-color-neutral-fill-quiet);
+  }
+
+  .custom-pagination::part(pages) {
+    gap: var(--cs-space-2xs);
+    flex-wrap: nowrap;
+  }
+
+  .custom-pagination::part(button) {
+    min-width: 2.5em;
+    height: 2.5em;
+    border: none;
+    border-radius: var(--cs-border-radius-pill);
+    font-weight: var(--cs-font-weight-semibold);
+    color: var(--cs-color-neutral-on-quiet);
+    background-color: transparent;
+    transition:
+      transform var(--cs-transition-fast),
+      color var(--cs-transition-fast),
+      background-color var(--cs-transition-fast);
+  }
+
+  .custom-pagination::part(button):hover {
+    color: var(--cs-color-neutral-on-normal);
+    background-color: var(--cs-color-neutral-fill-normal);
+    transform: translateY(-2px);
+  }
+
+  .custom-pagination::part(previous-button),
+  .custom-pagination::part(next-button),
+  .custom-pagination::part(first-button),
+  .custom-pagination::part(last-button) {
+    color: var(--cs-color-neutral-on-quiet);
+    background-color: var(--cs-color-neutral-fill-normal);
+  }
+
+  /* Keep the nav arrows neutral on hover so they stay calm next to the brand-tinted page numbers. */
+  .custom-pagination::part(previous-button):hover,
+  .custom-pagination::part(next-button):hover,
+  .custom-pagination::part(first-button):hover,
+  .custom-pagination::part(last-button):hover {
+    color: var(--cs-color-neutral-on-normal);
+    background-color: var(--cs-color-neutral-fill-normal);
+    filter: brightness(0.95);
+  }
+
+  .custom-pagination::part(page-current) {
+    color: var(--cs-color-brand-on-loud);
+    background-image: var(--gradient);
+    transform: none;
+  }
+
+  .custom-pagination::part(page-current):hover {
+    color: var(--cs-color-brand-on-loud);
+    transform: none;
+  }
+
+  .custom-pagination::part(ellipsis) {
+    color: var(--cs-color-neutral-on-quiet);
+    border: none;
+    background-color: transparent;
+  }
+</style>
+```
+
+## Accessibility Considerations
+
+Pagination ships with several accessibility behaviors built in:
+
+- **Page changes are announced.** When the page changes, the new position is announced to screen readers through a shared live region, so the update isn't silent.
+- **Focus follows the page.** After a control is activated, focus moves to the new current page rather than falling back to the top of the document, keeping keyboard users oriented.
+- **The current page is marked.** The active page carries `aria-current="page"`, and disabled or boundary controls carry `aria-disabled` so assistive technology skips them.
+- **Icons are direction-aware.** The previous, next, first, and last icons flip automatically in right-to-left languages.
+
+Give the control an accessible name with the `label` attribute whenever more than one pagination appears on a page, so screen reader users can tell them apart.
+
+## API
+
+### Importing
+
+If you're using the autoloader or a hosted project, components load on demand — no manual import
+needed. To cherry-pick this component, use one of the following snippets.
+
+**npm**
+
+```js
+import '@cruglobal/cornerstone-components/components/pagination/pagination.js';
+```
+
+**Self-Hosted**
+
+```js
+import './cornerstone/components/pagination/pagination.js';
+```
+
+**React**
+
+```js
+import CsPagination from '@cruglobal/cornerstone-components/react/pagination/index.js';
+```
+
+### Slots
+
+Valid slot names for this component (use exactly these — any other `slot` value is silently ignored and the element falls back to the default slot):
+
+- `first-icon` — An icon to use in lieu of the default first icon.
+- `last-icon` — An icon to use in lieu of the default last icon.
+- `next-icon` — An icon to use in lieu of the default next icon.
+- `previous-icon` — An icon to use in lieu of the default previous icon.
+
+### Attributes & Properties
+
+| Property | Attribute | Description | Type | Default | Reflects |
+| --- | --- | --- | --- | --- | --- |
+| `appearance` | `appearance` | The pagination's visual appearance. | `'outlined' \| 'filled' \| 'plain'` | `'outlined'` | Yes |
+| `boundaryCount` | `boundary-count` | The number of pages to always show at the start and end. | `number` | `1` | — |
+| `disabled` | `disabled` | Disables the pagination. | `boolean` | `false` | Yes |
+| `format` | `format` | The pagination's layout. The default `standard` format shows the full page list with ellipses; `compact` collapses it into a short "1 of 5" label flanked by the previous and next buttons, useful in tight spaces like toolbars and cards. | `'standard' \| 'compact'` | `'standard'` | Yes |
+| `hideSinglePage` | `hide-single-page` | Renders nothing when there's only one page. | `boolean` | `false` | — |
+| `hrefTemplate` | `href-template` | A URL template used to render page items as links instead of buttons. When set, items render as `<a>` elements for SSR, SEO, and no-JS support. Provide a string with `{page}` as a placeholder for the page number, e.g. `/products?page={page}`. In JavaScript, you can also assign a function that receives the page number and returns the URL, e.g. `el.hrefTemplate = page => \`/products?page=${page}\``. | `string \| ((page: number) => string)` | `''` | — |
+| `label` | `label` | A label that describes the pagination to assistive devices. This won't be shown on the screen, but it will be announced by screen readers. Especially useful when more than one pagination control exists on the same page. | `string` | `''` | — |
+| `page` | `page` | The current page, starting at 1. | `number` | `1` | Yes |
+| `pageSize` | `page-size` | The number of items shown per page. | `number` | `10` | — |
+| `siblingCount` | `sibling-count` | The number of pages to show on each side of the current page. | `number` | `2` | — |
+| `total` | `total` | The total number of items to paginate. | `number` | `0` | — |
+| `totalPages` | — | The total number of pages, derived from `total` and `pageSize`. | — | — | — |
+| `withEdges` | `with-edges` | Shows buttons that jump to the first and last pages. | `boolean` | `false` | — |
+| `withoutNav` | `without-nav` | Hides the previous and next buttons. | `boolean` | `false` | — |
+| `withSummary` | `with-summary` | Shows a summary of the items on the current page, e.g. "1–10 of 237". | `boolean` | `false` | — |
+
+### Events
+
+| Name | Description |
+| --- | --- |
+| `cs-after-page-change` | Emitted after the page changes. |
+| `cs-page-change` | Emitted when the page is about to change but before it does. Canceling this event with `event.preventDefault()` prevents the page from changing. |
+
+### Custom States
+
+| Name | Description | CSS selector |
+| --- | --- | --- |
+| `disabled` | Applied when the pagination is disabled. | `:state(disabled)` |
+
+### CSS Parts
+
+| Name | Description | CSS selector |
+| --- | --- | --- |
+| `button` | Every button or link, including page numbers and navigation controls. | `::part(button)` |
+| `ellipsis` | An ellipsis for collapsed pages. Acts as a button that jumps several pages toward that side. | `::part(ellipsis)` |
+| `first-button` | The first button. | `::part(first-button)` |
+| `label` | The "1 of 5" label shown between the navigation buttons in the `compact` layout. | `::part(label)` |
+| `last-button` | The last button. | `::part(last-button)` |
+| `next-button` | The next button. | `::part(next-button)` |
+| `page` | A page number button or link. | `::part(page)` |
+| `page-current` | The current page number button or link. | `::part(page-current)` |
+| `pages` | The list that wraps the page number items. | `::part(pages)` |
+| `pagination` | The component's outer wrapper, a `<nav>` element. | `::part(pagination)` |
+| `previous-button` | The previous button. | `::part(previous-button)` |
+| `summary` | The summary of items on the current page, shown with the `with-summary` attribute. | `::part(summary)` |
+
+### Dependencies
+
+- `<cs-icon>`

package/dist/bundled/skills/cornerstone/references/components/popover.md

@@ -0,0 +1,218 @@
+# Popover
+
+**Full documentation:** https://cruglobal.github.io/cornerstone-design-system/components/popover
+
+```html
+<cs-popover for="popover__overview">
+  <div class="cs-stack">
+    <p>This popover contains interactive content that users can engage with directly.</p>
+    <cs-button appearance="filled" variant="brand" size="s">Take Action</cs-button>
+  </div>
+</cs-popover>
+
+<cs-button appearance="filled" id="popover__overview">Show popover</cs-button>
+```
+
+Unlike [tooltips](https://cruglobal.github.io/cornerstone-design-system/components/tooltip), popovers can contain links, buttons, and form controls. They appear without an overlay and close when you click outside or press [[Escape]]. Only one popover can be open at a time.
+
+## Examples
+
+### Anchor
+
+Use `<cs-button>` or `<button>` elements as popover anchors. Connect the popover to its anchor by setting the `for` attribute to match the anchor's `id`.
+
+```html
+<cs-button appearance="filled" id="popover__anchor-button">Show Popover</cs-button>
+
+<cs-popover for="popover__anchor-button"> I'm anchored to a Cornerstone button. </cs-popover>
+
+<br /><br />
+
+<button class="cs-filled" id="popover__anchor-native-button">Show Popover</button>
+
+<cs-popover for="popover__anchor-native-button"> I'm anchored to a native button. </cs-popover>
+```
+
+> **Warning**
+>
+> <strong>The anchor must exist in the DOM before the popover connects.</strong><br />
+> Otherwise the popover won't attach and you'll see a console warning.
+
+### Opening & Closing
+
+Popovers show when you click their anchor element. You can also control them programmatically by setting the `open` property to `true` or `false`.
+
+Use `data-popover="close"` on any button inside a popover to close it automatically.
+
+```html
+<cs-popover for="popover__opening">
+  <p>The button below has <code>data-popover="close"</code> so clicking it will close the popover.</p>
+  <cs-button appearance="filled" data-popover="close" variant="brand">Dismiss</cs-button>
+</cs-popover>
+
+<cs-button appearance="filled" id="popover__opening">Show popover</cs-button>
+```
+
+### Placement
+
+Use the `placement` attribute to set where the popover appears relative to its anchor. The popover will automatically reposition if there isn't enough space in the preferred location. The default placement is `top`.
+
+```html
+<div class="cs-cluster">
+  <cs-button appearance="filled" id="popover__top">Top</cs-button>
+  <cs-popover for="popover__top" placement="top">I'm on the top</cs-popover>
+
+  <cs-button appearance="filled" id="popover__bottom">Bottom</cs-button>
+  <cs-popover for="popover__bottom" placement="bottom">I'm on the bottom</cs-popover>
+
+  <cs-button appearance="filled" id="popover__left">Left</cs-button>
+  <cs-popover for="popover__left" placement="left">I'm on the left</cs-popover>
+
+  <cs-button appearance="filled" id="popover__right">Right</cs-button>
+  <cs-popover for="popover__right" placement="right">I'm on the right</cs-popover>
+</div>
+```
+
+### Distance
+
+Use the `distance` attribute to control how far the popover appears from its anchor.
+
+```html
+<div class="cs-cluster">
+  <cs-button appearance="filled" id="popover__distance-near">Near</cs-button>
+  <cs-popover for="popover__distance-near" distance="0">I'm very close</cs-popover>
+
+  <cs-button appearance="filled" id="popover__distance-far">Far</cs-button>
+  <cs-popover for="popover__distance-far" distance="30">I'm farther away</cs-popover>
+</div>
+```
+
+### Arrow Size
+
+Use the `--arrow-size` custom property to change the size of the popover's arrow. To remove it, use the `without-arrow` attribute.
+
+```html
+<div class="cs-cluster">
+  <cs-button appearance="filled" id="popover__big-arrow">Big arrow</cs-button>
+  <cs-popover for="popover__big-arrow" style="--arrow-size: 8px;">I have a big arrow</cs-popover>
+
+  <cs-button appearance="filled" id="popover__no-arrow">No arrow</cs-button>
+  <cs-popover for="popover__no-arrow" without-arrow>I don't have an arrow</cs-popover>
+</div>
+```
+
+### Max Width
+
+Use the `--max-width` custom property to control the maximum width of the popover.
+
+```html
+<cs-button appearance="filled" id="popover__max-width">Toggle me</cs-button>
+<cs-popover for="popover__max-width" style="--max-width: 160px;">
+  Popovers will usually grow to be much wider, but this one has a custom max width that forces text to wrap.
+</cs-popover>
+```
+
+### Initial Focus
+
+Use the [`autofocus`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus) global attribute to move focus to a specific form control when the popover opens.
+
+```html
+<cs-popover for="popover__autofocus">
+  <div class="cs-stack">
+    <cs-textarea autofocus placeholder="What's on your mind?" size="s" resize="none" rows="2"></cs-textarea>
+    <cs-button appearance="filled" variant="brand" size="s" data-popover="close"> Submit </cs-button>
+  </div>
+</cs-popover>
+
+<cs-button appearance="filled" id="popover__autofocus">
+  <cs-icon name="chat_bubble" slot="start"></cs-icon>
+  Feedback
+</cs-button>
+```
+
+## API
+
+### Importing
+
+If you're using the autoloader or a hosted project, components load on demand — no manual import
+needed. To cherry-pick this component, use one of the following snippets.
+
+**npm**
+
+```js
+import '@cruglobal/cornerstone-components/components/popover/popover.js';
+```
+
+**Self-Hosted**
+
+```js
+import './cornerstone/components/popover/popover.js';
+```
+
+**React**
+
+```js
+import CsPopover from '@cruglobal/cornerstone-components/react/popover/index.js';
+```
+
+### Slots
+
+Valid slot names for this component (use exactly these — any other `slot` value is silently ignored and the element falls back to the default slot):
+
+- `(default)` — The popover's content. Interactive elements such as buttons and links are supported.
+
+### Attributes & Properties
+
+| Property | Attribute | Description | Type | Default | Reflects |
+| --- | --- | --- | --- | --- | --- |
+| `distance` | `distance` | The distance in pixels from which to offset the popover away from its target. | `number` | `8` | — |
+| `for` | `for` | The ID of the popover's anchor element. This must be an interactive/focusable element such as a button. | `string \| null` | `null` | — |
+| `open` | `open` | Shows or hides the popover. | `boolean` | `false` | Yes |
+| `placement` | `placement` | The preferred placement of the popover. Note that the actual placement may vary as needed to keep the popover inside of the viewport. | `'top' \| 'top-start' \| 'top-end' \| 'right' \| 'right-start' \| 'right-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end'` | `'top'` | — |
+| `skidding` | `skidding` | The distance in pixels from which to offset the popover along its target. | `number` | `0` | — |
+| `withoutArrow` | `without-arrow` | Removes the arrow from the popover. | `boolean` | `false` | Yes |
+
+### Methods
+
+| Name | Description | Arguments |
+| --- | --- | --- |
+| `hide()` | Hides the popover. | — |
+| `show()` | Shows the popover. | — |
+
+### Events
+
+| Name | Description |
+| --- | --- |
+| `cs-after-hide` | Emitted after the popover has hidden and all animations are complete. |
+| `cs-after-show` | Emitted after the popover has shown and all animations are complete. |
+| `cs-hide` | Emitted when the popover begins to hide. Canceling this event will stop the popover from hiding. |
+| `cs-show` | Emitted when the popover begins to show. Canceling this event will stop the popover from showing. |
+
+### CSS Custom Properties
+
+| Name | Description | Default |
+| --- | --- | --- |
+| `--arrow-size` | The size of the tiny arrow that points to the popover (set to zero to remove). | `0.375rem` |
+| `--hide-duration` | The speed of the hide animation. | `var(--cs-transition-fast)` |
+| `--max-width` | The maximum width of the popover's body content. | `25rem` |
+| `--show-duration` | The speed of the show animation. | `var(--cs-transition-fast)` |
+
+### Custom States
+
+| Name | Description | CSS selector |
+| --- | --- | --- |
+| `open` | Applied when the popover is open. | `:state(open)` |
+
+### CSS Parts
+
+| Name | Description | CSS selector |
+| --- | --- | --- |
+| `body` | The popover's body where its content is rendered. | `::part(body)` |
+| `dialog` | The native dialog element that contains the popover content. | `::part(dialog)` |
+| `popup` | The internal `<cs-popup>` element that positions the popover. | `::part(popup)` |
+| `popup__arrow` | The popup's exported `arrow` part. Use this to target the popover's arrow. | `::part(popup__arrow)` |
+| `popup__popup` | The popup's exported `popup` part. Use this to target the popover's popup container. | `::part(popup__popup)` |
+
+### Dependencies
+
+- `<cs-popup>`