@phcdevworks/spectre-components 1.12.0 → 1.15.0

package/README.md

@@ -4,10 +4,10 @@
 Spectre system. It implements Spectre's design contracts as reusable,
 accessible, framework-agnostic web components.
 
-Maintained by [PHCDevworks](https://go.phcdev.co). It draws on Spectre's
-token and styling contracts to ship drop-in UI primitives, so applications
-that need working components — rather than raw CSS or recipes to assemble
-themselves — can consume Spectre without a framework-specific adapter.
+Maintained by [PHCDevworks](https://go.phcdev.co). It draws on Spectre's token
+and styling contracts to ship drop-in UI primitives, so applications that need
+working components — rather than raw CSS or recipes to assemble themselves — can
+consume Spectre without a framework-specific adapter.
 
 ## Repository Snapshot
 
@@ -16,7 +16,7 @@ themselves — can consume Spectre without a framework-specific adapter.
 | Project team           | `project-design`                    |
 | Repository role        | Spectre L3a Lit web component layer |
 | Package/artifact       | `@phcdevworks/spectre-components`   |
-| Current version/status | 1.12.0                              |
+| Current version/status | 1.15.0                              |
 
 ## Standard Workflow
 
@@ -327,32 +327,38 @@ design-system-level decision.
 
 ### sp-button
 
-Renders a `<button>` with Spectre variant, size, loading, and pill support.
+Renders a `<button>` with Spectre variant, size, loading, and pill support. Set
+`href` to render a native `<a>` instead, styled with the same classes — useful
+when the button needs to navigate rather than submit/act.
 
 **Attributes**
 
-| Attribute          | Type                                                                  | Default   | Description                                              |
-| ------------------ | --------------------------------------------------------------------- | --------- | -------------------------------------------------------- |
-| `variant`          | `primary \| secondary \| ghost \| danger \| success \| cta \| accent` | `primary` | Visual style                                             |
-| `size`             | `sm \| md \| lg`                                                      | `md`      | Control size                                             |
-| `type`             | `button \| submit \| reset`                                           | `button`  | Native button type                                       |
-| `label`            | string                                                                | —         | Text label (overridden by content projection)            |
-| `loading`          | boolean                                                               | `false`   | Busy state — disables the button and shows loading label |
-| `loading-label`    | string                                                                | `Loading` | Accessible text shown during loading                     |
-| `disabled`         | boolean                                                               | `false`   | Disables the button                                      |
-| `full-width`       | boolean                                                               | `false`   | Spans full container width                               |
-| `pill`             | boolean                                                               | `false`   | Pill / fully-rounded corners                             |
-| `name`             | string                                                                | —         | Form field name                                          |
-| `value`            | string                                                                | `''`      | Submitted value                                          |
-| `form`             | string                                                                | —         | Associates with a form by ID                             |
-| `autofocus`        | boolean                                                               | `false`   | Autofocus on page load                                   |
-| `id`               | string                                                                | —         | Forwarded to the native `<button>`                       |
-| `title`            | string                                                                | —         | Forwarded to the native `<button>`                       |
-| `aria-label`       | string                                                                | —         | Forwarded to the native `<button>`                       |
-| `aria-labelledby`  | string                                                                | —         | Forwarded to the native `<button>`                       |
-| `aria-describedby` | string                                                                | —         | Forwarded to the native `<button>`                       |
-
-**Events** — native button events bubble normally (`click`, `focus`, `blur`).
+| Attribute          | Type                                                                  | Default   | Description                                                                   |
+| ------------------ | --------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
+| `variant`          | `primary \| secondary \| ghost \| danger \| success \| cta \| accent` | `primary` | Visual style                                                                  |
+| `size`             | `sm \| md \| lg`                                                      | `md`      | Control size                                                                  |
+| `type`             | `button \| submit \| reset`                                           | `button`  | Native button type (ignored when rendered as a link)                          |
+| `href`             | string                                                                | —         | Renders `<a href>` instead of `<button>` (unless `disabled`/`loading`)        |
+| `target`           | `_blank \| _self \| _parent \| _top`                                  | —         | Forwarded to the native `<a>` when `href` is set                              |
+| `rel`              | string                                                                | —         | Forwarded to the native `<a>` when `href` is set                              |
+| `label`            | string                                                                | —         | Text label (overridden by content projection)                                 |
+| `loading`          | boolean                                                               | `false`   | Busy state — disables the button/link and shows loading label                 |
+| `loading-label`    | string                                                                | `Loading` | Accessible text shown during loading                                          |
+| `disabled`         | boolean                                                               | `false`   | Disables the button; if `href` is also set, still renders `<button disabled>` |
+| `full-width`       | boolean                                                               | `false`   | Spans full container width                                                    |
+| `pill`             | boolean                                                               | `false`   | Pill / fully-rounded corners                                                  |
+| `name`             | string                                                                | —         | Form field name                                                               |
+| `value`            | string                                                                | `''`      | Submitted value                                                               |
+| `form`             | string                                                                | —         | Associates with a form by ID                                                  |
+| `autofocus`        | boolean                                                               | `false`   | Autofocus on page load                                                        |
+| `id`               | string                                                                | —         | Forwarded to the native element                                               |
+| `title`            | string                                                                | —         | Forwarded to the native element                                               |
+| `aria-label`       | string                                                                | —         | Forwarded to the native element                                               |
+| `aria-labelledby`  | string                                                                | —         | Forwarded to the native element                                               |
+| `aria-describedby` | string                                                                | —         | Forwarded to the native element                                               |
+
+**Events** — native button/link events bubble normally (`click`, `focus`,
+`blur`).
 
 **Content projection** — place children inside `<sp-button>` to use them as
 button content instead of the `label` property:
@@ -364,7 +370,16 @@ button content instead of the `label` property:
 </sp-button>
 ```
 
-**Internal target** — `[data-sp-button-native]` selects the native `<button>`.
+**Link mode:**
+
+```html
+<sp-button variant="secondary" href="/pricing" target="_blank" rel="noopener">
+  View pricing
+</sp-button>
+```
+
+**Internal target** — `[data-sp-button-native]` selects the native `<button>` or
+`<a>`.
 
 ---
 
@@ -797,16 +812,41 @@ price, feature list, call-to-action, etc.).
 
 ---
 
+### Layout components
+
+`sp-container`, `sp-grid`, `sp-section`, `sp-stack`, `sp-footer`, and `sp-nav`
+share two contracts:
+
+- **Host display** — the host element defaults to `display: block` (set via
+  inline style in `connectedCallback`, so a consumer's own
+  `style="display: ..."` always wins) instead of the browser's default inline
+  custom-element box. This keeps backgrounds, margins, and full-width inner
+  content from being trapped inside an inline box.
+- **`inner-class`** — an `inner-class` attribute (`innerClass` JS property)
+  appends consumer-supplied Spectre utility classes to the native inner element
+  the component's recipe classes render on, without touching the host's own
+  `class` attribute. Host `class` and `inner-class` are distinct targets: host
+  `class` affects the custom-element box itself, `inner-class` affects the
+  styled element inside it. Only tokens matching `sp-*` (Spectre utility class
+  syntax) are applied; anything else is silently dropped.
+
+```html
+<sp-stack class="my-host-hook" inner-class="sp-bg-primary-500 sp-p-8">
+  ...
+</sp-stack>
+```
+
 ### sp-container
 
 Renders a `<div>` layout container backed by the Spectre container recipe.
 
 **Attributes**
 
-| Attribute                 | Type    | Default | Description                       |
-| ------------------------- | ------- | ------- | --------------------------------- |
-| `max-width`               | `prose` | —       | Constrains content to a max width |
-| `id` / `title` / `aria-*` | string  | —       | Forwarded to the native `<div>`   |
+| Attribute                 | Type    | Default | Description                                           |
+| ------------------------- | ------- | ------- | ----------------------------------------------------- |
+| `max-width`               | `prose` | —       | Constrains content to a max width                     |
+| `inner-class`             | string  | —       | Spectre utility classes applied to the native `<div>` |
+| `id` / `title` / `aria-*` | string  | —       | Forwarded to the native `<div>`                       |
 
 **Content projection** — children become the container content.
 
@@ -820,11 +860,13 @@ Renders a `<div>` grid layout backed by the Spectre grid recipe.
 
 **Attributes**
 
-| Attribute                 | Type                          | Default | Description                     |
-| ------------------------- | ----------------------------- | ------- | ------------------------------- |
-| `columns`                 | `1 \| 2 \| 3 \| 4 \| 6 \| 12` | `1`     | Number of grid columns          |
-| `gap`                     | `sm \| md \| lg`              | `md`    | Gap between grid items          |
-| `id` / `title` / `aria-*` | string                        | —       | Forwarded to the native `<div>` |
+| Attribute                 | Type                                                         | Default | Description                                                 |
+| ------------------------- | ------------------------------------------------------------ | ------- | ----------------------------------------------------------- |
+| `columns`                 | `1 \| 2 \| 3 \| 4 \| 6 \| 12`                                | `1`     | Number of grid columns                                      |
+| `gap`                     | `sm \| md \| lg`                                             | `md`    | Gap between grid items                                      |
+| `span`                    | `1-12 \| 'full'` or `{ base?, md?, lg? }` (JS property only) | —       | Column span for a grid item, single value or per-breakpoint |
+| `inner-class`             | string                                                       | —       | Spectre utility classes applied to the native `<div>`       |
+| `id` / `title` / `aria-*` | string                                                       | —       | Forwarded to the native `<div>`                             |
 
 **Content projection** — children become grid items.
 
@@ -838,9 +880,10 @@ Renders a `<section>` layout wrapper backed by the Spectre section recipe.
 
 **Attributes**
 
-| Attribute                 | Type   | Default | Description                         |
-| ------------------------- | ------ | ------- | ----------------------------------- |
-| `id` / `title` / `aria-*` | string | —       | Forwarded to the native `<section>` |
+| Attribute                 | Type   | Default | Description                                               |
+| ------------------------- | ------ | ------- | --------------------------------------------------------- |
+| `inner-class`             | string | —       | Spectre utility classes applied to the native `<section>` |
+| `id` / `title` / `aria-*` | string | —       | Forwarded to the native `<section>`                       |
 
 **Content projection** — children become the section content.
 
@@ -854,12 +897,13 @@ Renders a `<div>` flex stack backed by the Spectre stack recipe.
 
 **Attributes**
 
-| Attribute                 | Type                     | Default    | Description                           |
-| ------------------------- | ------------------------ | ---------- | ------------------------------------- |
-| `direction`               | `vertical \| horizontal` | `vertical` | Stack axis                            |
-| `basis`                   | `sidebar`                | —          | Reserves sidebar-sized basis on items |
-| `align`                   | `center \| stretch`      | `center`   | Cross-axis alignment                  |
-| `id` / `title` / `aria-*` | string                   | —          | Forwarded to the native `<div>`       |
+| Attribute                 | Type                     | Default    | Description                                           |
+| ------------------------- | ------------------------ | ---------- | ----------------------------------------------------- |
+| `direction`               | `vertical \| horizontal` | `vertical` | Stack axis                                            |
+| `basis`                   | `sidebar`                | —          | Reserves sidebar-sized basis on items                 |
+| `align`                   | `center \| stretch`      | `center`   | Cross-axis alignment                                  |
+| `inner-class`             | string                   | —          | Spectre utility classes applied to the native `<div>` |
+| `id` / `title` / `aria-*` | string                   | —          | Forwarded to the native `<div>`                       |
 
 **Content projection** — children become stack items.
 
@@ -873,14 +917,15 @@ Renders a `<footer>` backed by the Spectre footer recipe.
 
 **Attributes**
 
-| Attribute                 | Type    | Default | Description                        |
-| ------------------------- | ------- | ------- | ---------------------------------- |
-| `bordered`                | boolean | `false` | Adds a top border                  |
-| `full-width`              | boolean | `false` | Spans full container width         |
-| `id` / `title` / `aria-*` | string  | —       | Forwarded to the native `<footer>` |
+| Attribute                 | Type    | Default | Description                                              |
+| ------------------------- | ------- | ------- | -------------------------------------------------------- |
+| `bordered`                | boolean | `false` | Adds a top border                                        |
+| `full-width`              | boolean | `false` | Spans full container width                               |
+| `inner-class`             | string  | —       | Spectre utility classes applied to the native `<footer>` |
+| `id` / `title` / `aria-*` | string  | —       | Forwarded to the native `<footer>`                       |
 
-**Content projection** — children become the footer content (links, legal
-text, etc.).
+**Content projection** — children become the footer content (links, legal text,
+etc.).
 
 **Internal target** — `[data-sp-footer-native]` selects the native `<footer>`.
 
@@ -892,12 +937,13 @@ Renders a `<nav>` backed by the Spectre nav recipe.
 
 **Attributes**
 
-| Attribute                 | Type    | Default | Description                     |
-| ------------------------- | ------- | ------- | ------------------------------- |
-| `bordered`                | boolean | `false` | Adds a bottom border            |
-| `sticky`                  | boolean | `false` | Sticks the nav to the viewport  |
-| `full-width`              | boolean | `false` | Spans full container width      |
-| `id` / `title` / `aria-*` | string  | —       | Forwarded to the native `<nav>` |
+| Attribute                 | Type    | Default | Description                                           |
+| ------------------------- | ------- | ------- | ----------------------------------------------------- |
+| `bordered`                | boolean | `false` | Adds a bottom border                                  |
+| `sticky`                  | boolean | `false` | Sticks the nav to the viewport                        |
+| `full-width`              | boolean | `false` | Spans full container width                            |
+| `inner-class`             | string  | —       | Spectre utility classes applied to the native `<nav>` |
+| `id` / `title` / `aria-*` | string  | —       | Forwarded to the native `<nav>`                       |
 
 **Content projection** — children become the nav content (links, brand mark,
 etc.).
@@ -908,30 +954,31 @@ etc.).
 
 ### sp-nav-item
 
-Renders a nav link that can optionally become a dropdown trigger, backed by
-the same Spectre dropdown recipe as `sp-dropdown`. Place it inside `sp-nav`
+Renders a nav link that can optionally become a dropdown trigger, backed by the
+same Spectre dropdown recipe as `sp-dropdown`. Place it inside `sp-nav`
 alongside plain `<a>` links.
 
 **Attributes**
 
-| Attribute                 | Type    | Default          | Description                                                         |
-| ------------------------- | ------- | ---------------- | ------------------------------------------------------------------- |
-| `dropdown`                | boolean | `false`          | Renders a dropdown trigger + menu instead of a plain `<a>`          |
-| `href`                    | string  | —                | Link target when `dropdown` is `false`                              |
-| `label`                   | string  | —                | Trigger/link text when no content is projected                      |
-| `open`                    | boolean | `false`          | Open/closed menu state (dropdown mode only)                         |
-| `placement`               | string  | `'bottom-start'` | Menu position: `bottom-start`, `bottom-end`, `top-start`, `top-end` |
-| `id` / `title` / `aria-*` | string  | —                | Forwarded to the rendered `<a>` or trigger `<button>`               |
-
-**Content projection** — in dropdown mode, children become the menu content;
-a child with `slot="trigger"` becomes the trigger content instead of `label`.
-Menu content can be a plain list of links or an `sp-grid` for a full mega-menu
+| Attribute                 | Type    | Default          | Description                                                                                                              |
+| ------------------------- | ------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `dropdown`                | boolean | `false`          | Renders a dropdown trigger + menu instead of a plain `<a>`                                                               |
+| `href`                    | string  | —                | Link target when `dropdown` is `false`                                                                                   |
+| `label`                   | string  | —                | Trigger/link text when no content is projected                                                                           |
+| `mega`                    | boolean | `false`          | Anchors the menu to the nearest positioned ancestor instead of the trigger, spanning its full width (dropdown mode only) |
+| `open`                    | boolean | `false`          | Open/closed menu state (dropdown mode only)                                                                              |
+| `placement`               | string  | `'bottom-start'` | Menu position: `bottom-start`, `bottom-end`, `top-start`, `top-end`                                                      |
+| `id` / `title` / `aria-*` | string  | —                | Forwarded to the rendered `<a>` or trigger `<button>`                                                                    |
+
+**Content projection** — in dropdown mode, children become the menu content; a
+child with `slot="trigger"` becomes the trigger content instead of `label`. Menu
+content can be a plain list of links or an `sp-grid` for a full mega-menu
 layout. In link mode, children become the link's content.
 
 **Events** — `sp-open` and `sp-close` (dropdown mode only), both `bubbles`.
 
-**Internal targets** — `[data-sp-nav-item-trigger]` selects the trigger
-button; `[data-sp-nav-item-menu]` selects the menu panel.
+**Internal targets** — `[data-sp-nav-item-trigger]` selects the trigger button;
+`[data-sp-nav-item-menu]` selects the menu panel.
 
 ```html
 <sp-nav>
@@ -943,9 +990,20 @@ button; `[data-sp-nav-item-menu]` selects the menu panel.
       <div>Column three</div>
     </sp-grid>
   </sp-nav-item>
+  <sp-nav-item dropdown mega label="Solutions">
+    <sp-grid columns="4" gap="lg">
+      <div>Column one</div>
+      <div>Column two</div>
+      <div>Column three</div>
+      <div>Column four</div>
+    </sp-grid>
+  </sp-nav-item>
 </sp-nav>
 ```
 
+`mega` requires a positioned ancestor to anchor against — `sp-nav` is a
+positioning context by default, so nesting inside it is sufficient.
+
 ---
 
 ### sp-sidebar
@@ -955,12 +1013,13 @@ Spectre sidebar recipe.
 
 **Attributes**
 
-| Attribute                 | Type    | Default          | Description                            |
-| ------------------------- | ------- | ---------------- | -------------------------------------- |
-| `bordered`                | boolean | `false`          | Adds a trailing border                 |
-| `open`                    | boolean | `false`          | Open/closed off-canvas state           |
-| `toggle-label`            | string  | `Toggle sidebar` | Accessible label for the toggle button |
-| `id` / `title` / `aria-*` | string  | —                | Forwarded to the native `<aside>`      |
+| Attribute                 | Type    | Default          | Description                                                                           |
+| ------------------------- | ------- | ---------------- | ------------------------------------------------------------------------------------- |
+| `bordered`                | boolean | `false`          | Adds a trailing border                                                                |
+| `hide-toggle`             | boolean | `false`          | Suppresses the built-in toggle button (e.g. when using `sp-sidebar-toggle` elsewhere) |
+| `open`                    | boolean | `false`          | Open/closed off-canvas state                                                          |
+| `toggle-label`            | string  | `Toggle sidebar` | Accessible label for the built-in toggle button                                       |
+| `id` / `title` / `aria-*` | string  | —                | Forwarded to the native `<aside>`                                                     |
 
 **Content projection** — children become the sidebar content (links, navigation
 groups, etc.).
@@ -977,6 +1036,45 @@ hide the off-canvas panel and backdrop.
 
 ---
 
+### sp-sidebar-toggle
+
+Renders a standalone trigger button that opens/closes a remote `sp-sidebar`,
+backed by the Spectre sidebar-toggle recipe. Use it to place a toggle somewhere
+other than inside the sidebar itself (a header, a nav bar) — pair it with
+`hide-toggle` on the target `sp-sidebar` to suppress that sidebar's own built-in
+toggle, or leave both in place to control the same sidebar from two triggers.
+
+**Attributes**
+
+| Attribute                 | Type   | Default          | Description                                                                                      |
+| ------------------------- | ------ | ---------------- | ------------------------------------------------------------------------------------------------ |
+| `for`                     | string | —                | `id` of the target `sp-sidebar`'s native content (the id set on the `sp-sidebar` element itself) |
+| `label`                   | string | `Toggle sidebar` | Accessible label when no icon content is projected                                               |
+| `id` / `title` / `aria-*` | string | —                | Forwarded to the native `<button>`                                                               |
+
+**Content projection** — children become the button's icon content; falls back
+to a default `☰` glyph when empty.
+
+**Behavior** — clicking the button toggles the target `sp-sidebar`'s `open`
+property and mirrors its own `aria-expanded` state, including staying in sync
+when the target is opened/closed by another trigger (its own built-in toggle,
+the backdrop, `Esc`, or a second `sp-sidebar-toggle`).
+
+```html
+<sp-nav>
+  <sp-sidebar-toggle for="app-sidebar"></sp-sidebar-toggle>
+</sp-nav>
+
+<sp-sidebar id="app-sidebar" hide-toggle>
+  <a href="/dashboard">Dashboard</a>
+</sp-sidebar>
+```
+
+**Internal target** — `[data-sp-sidebar-toggle-native]` selects the native
+`<button>`.
+
+---
+
 ### sp-dropdown
 
 Renders a trigger button and a menu container, backed by the Spectre dropdown
@@ -984,13 +1082,14 @@ recipes.
 
 **Attributes**
 
-| Attribute                 | Type                                                 | Default        | Description                                                                   |
-| ------------------------- | ---------------------------------------------------- | -------------- | ----------------------------------------------------------------------------- |
-| `open`                    | boolean                                              | `false`        | Open/closed menu state                                                        |
-| `placement`               | `bottom-start \| bottom-end \| top-start \| top-end` | `bottom-start` | Menu position relative to trigger                                             |
-| `full-width`              | boolean                                              | `false`        | Spans full container width                                                    |
-| `trigger-label`           | string                                               | `Toggle menu`  | Visible/accessible trigger text when no `slot="trigger"` content is projected |
-| `id` / `title` / `aria-*` | string                                               | —              | Forwarded to the trigger button                                               |
+| Attribute                 | Type                                                 | Default        | Description                                                                                         |
+| ------------------------- | ---------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------- |
+| `open`                    | boolean                                              | `false`        | Open/closed menu state                                                                              |
+| `placement`               | `bottom-start \| bottom-end \| top-start \| top-end` | `bottom-start` | Menu position relative to trigger                                                                   |
+| `full-width`              | boolean                                              | `false`        | Spans full container width                                                                          |
+| `mega`                    | boolean                                              | `false`        | Anchors the menu to the nearest positioned ancestor instead of the trigger, spanning its full width |
+| `trigger-label`           | string                                               | `Toggle menu`  | Visible/accessible trigger text when no `slot="trigger"` content is projected                       |
+| `id` / `title` / `aria-*` | string                                               | —              | Forwarded to the trigger button                                                                     |
 
 **Content projection** — an element with `slot="trigger"` becomes the trigger
 button content; all other children become the menu content.
@@ -1096,13 +1195,14 @@ switches with `level` while the recipe call and styling stay the same.
 
 **Attributes**
 
-| Attribute                 | Type                                                    | Default   | Description                            |
-| ------------------------- | -------------------------------------------------------- | --------- | --------------------------------------- |
-| `level`                   | `h1 \| h2 \| h3 \| h4 \| h5 \| h6 \| p \| span`          | `p`       | Rendered element tag                    |
-| `size`                    | `xs \| sm \| md \| lg \| xl \| 2xl \| 3xl \| 4xl \| 5xl \| 6xl` | `md` | Text size scale                         |
-| `variant`                 | `default \| muted \| subtle \| meta \| brand`            | `default` | Text color role                         |
-| `family`                  | `sans \| serif \| mono`                                  | —         | Optional font family override           |
-| `id` / `title` / `aria-*` | string                                                    | —         | Forwarded to the rendered native element |
+| Attribute                 | Type                                                            | Default   | Description                              |
+| ------------------------- | --------------------------------------------------------------- | --------- | ---------------------------------------- |
+| `level`                   | `h1 \| h2 \| h3 \| h4 \| h5 \| h6 \| p \| span`                 | `p`       | Rendered element tag                     |
+| `size`                    | `xs \| sm \| md \| lg \| xl \| 2xl \| 3xl \| 4xl \| 5xl \| 6xl` | `md`      | Text size scale                          |
+| `variant`                 | `default \| muted \| subtle \| meta \| brand`                   | `default` | Text color role                          |
+| `family`                  | `sans \| serif \| mono`                                         | —         | Optional font family override            |
+| `transform`               | `none \| uppercase \| lowercase \| capitalize`                  | —         | Optional text transform                  |
+| `id` / `title` / `aria-*` | string                                                          | —         | Forwarded to the rendered native element |
 
 **Content projection** — children become the text content.
 
@@ -1179,45 +1279,47 @@ defineSpectreComponents() // registers all sp-* elements
 **Interactive constants and types**: `spectreDropdownPlacements`,
 `spectreToastVariants`, `spectreTooltipPlacements`, `SpectreDropdownPlacement`,
 `SpectreToastVariant`, `SpectreTooltipPlacement`, `SpectreFooterProps`,
-`SpectreNavProps`, `SpectreSidebarProps`, `SpectreDropdownProps`,
-`SpectreModalProps`, `SpectreToastProps`, `SpectreTooltipProps`
+`SpectreNavProps`, `SpectreSidebarProps`, `SpectreSidebarToggleProps`,
+`SpectreDropdownProps`, `SpectreModalProps`, `SpectreToastProps`,
+`SpectreTooltipProps`
 
 ### Subpath entry points
 
 Each entry point registers only that component and exports only its surface:
 
-| Entry point        | Registers         | Key exports                                                                              |
-| ------------------ | ----------------- | ---------------------------------------------------------------------------------------- |
-| `.../button`       | `sp-button`       | `defineSpectreButton`, `SpectreButtonElement`, button constants and types                |
-| `.../input`        | `sp-input`        | `defineSpectreInput`, `SpectreInputElement`, input constants and types                   |
-| `.../textarea`     | `sp-textarea`     | `defineSpectreTextarea`, `SpectreTextareaElement`, `SpectreTextareaProps`                |
-| `.../select`       | `sp-select`       | `defineSpectreSelect`, `SpectreSelectElement`, `SpectreSelectProps`                      |
-| `.../checkbox`     | `sp-checkbox`     | `defineSpectreCheckbox`, `SpectreCheckboxElement`, `SpectreCheckboxProps`                |
-| `.../radio`        | `sp-radio`        | `defineSpectreRadio`, `SpectreRadioElement`, `SpectreRadioProps`                         |
-| `.../label`        | `sp-label`        | `defineSpectreLabel`, `SpectreLabelElement`, `SpectreLabelProps`                         |
-| `.../fieldset`     | `sp-fieldset`     | `defineSpectreFieldset`, `SpectreFieldsetElement`, `SpectreFieldsetProps`                |
-| `.../badge`        | `sp-badge`        | `defineSpectreBadge`, `SpectreBadgeElement`, badge constants and types                   |
-| `.../card`         | `sp-card`         | `defineSpectreCard`, `SpectreCardElement`, card constants and types                      |
-| `.../icon-box`     | `sp-icon-box`     | `defineSpectreIconBox`, `SpectreIconBoxElement`, icon-box constants and types            |
-| `.../rating`       | `sp-rating`       | `defineSpectreRating`, `SpectreRatingElement`, rating constants and types                |
-| `.../testimonial`  | `sp-testimonial`  | `defineSpectreTestimonial`, `SpectreTestimonialElement`, testimonial constants and types |
-| `.../alert`        | `sp-alert`        | `defineSpectreAlert`, `SpectreAlertElement`, alert constants and types                   |
-| `.../avatar`       | `sp-avatar`       | `defineSpectreAvatar`, `SpectreAvatarElement`, avatar constants and types                |
-| `.../spinner`      | `sp-spinner`      | `defineSpectreSpinner`, `SpectreSpinnerElement`, spinner constants and types             |
-| `.../tag`          | `sp-tag`          | `defineSpectreTag`, `SpectreTagElement`, tag constants and types                         |
-| `.../pricing-card` | `sp-pricing-card` | `defineSpectrePricingCard`, `SpectrePricingCardElement`, `SpectrePricingCardProps`       |
-| `.../container`    | `sp-container`    | `defineSpectreContainer`, `SpectreContainerElement`, container constants and types       |
-| `.../grid`         | `sp-grid`         | `defineSpectreGrid`, `SpectreGridElement`, grid constants and types                      |
-| `.../section`      | `sp-section`      | `defineSpectreSection`, `SpectreSectionElement`, `SpectreSectionProps`                   |
-| `.../stack`        | `sp-stack`        | `defineSpectreStack`, `SpectreStackElement`, stack constants and types                   |
-| `.../nav`          | `sp-nav`          | `defineSpectreNav`, `SpectreNavElement`, `SpectreNavProps`                               |
-| `.../nav-item`     | `sp-nav-item`     | `defineSpectreNavItem`, `SpectreNavItemElement`, `SpectreNavItemProps`                   |
-| `.../sidebar`      | `sp-sidebar`      | `defineSpectreSidebar`, `SpectreSidebarElement`, `SpectreSidebarProps`                   |
-| `.../dropdown`     | `sp-dropdown`     | `defineSpectreDropdown`, `SpectreDropdownElement`, dropdown constants and types          |
-| `.../footer`       | `sp-footer`       | `defineSpectreFooter`, `SpectreFooterElement`, `SpectreFooterProps`                      |
-| `.../modal`        | `sp-modal`        | `defineSpectreModal`, `SpectreModalElement`, `SpectreModalProps`                         |
-| `.../toast`        | `sp-toast`        | `defineSpectreToast`, `SpectreToastElement`, toast constants and types                   |
-| `.../tooltip`      | `sp-tooltip`      | `defineSpectreTooltip`, `SpectreTooltipElement`, tooltip constants and types             |
+| Entry point          | Registers           | Key exports                                                                              |
+| -------------------- | ------------------- | ---------------------------------------------------------------------------------------- |
+| `.../button`         | `sp-button`         | `defineSpectreButton`, `SpectreButtonElement`, button constants and types                |
+| `.../input`          | `sp-input`          | `defineSpectreInput`, `SpectreInputElement`, input constants and types                   |
+| `.../textarea`       | `sp-textarea`       | `defineSpectreTextarea`, `SpectreTextareaElement`, `SpectreTextareaProps`                |
+| `.../select`         | `sp-select`         | `defineSpectreSelect`, `SpectreSelectElement`, `SpectreSelectProps`                      |
+| `.../checkbox`       | `sp-checkbox`       | `defineSpectreCheckbox`, `SpectreCheckboxElement`, `SpectreCheckboxProps`                |
+| `.../radio`          | `sp-radio`          | `defineSpectreRadio`, `SpectreRadioElement`, `SpectreRadioProps`                         |
+| `.../label`          | `sp-label`          | `defineSpectreLabel`, `SpectreLabelElement`, `SpectreLabelProps`                         |
+| `.../fieldset`       | `sp-fieldset`       | `defineSpectreFieldset`, `SpectreFieldsetElement`, `SpectreFieldsetProps`                |
+| `.../badge`          | `sp-badge`          | `defineSpectreBadge`, `SpectreBadgeElement`, badge constants and types                   |
+| `.../card`           | `sp-card`           | `defineSpectreCard`, `SpectreCardElement`, card constants and types                      |
+| `.../icon-box`       | `sp-icon-box`       | `defineSpectreIconBox`, `SpectreIconBoxElement`, icon-box constants and types            |
+| `.../rating`         | `sp-rating`         | `defineSpectreRating`, `SpectreRatingElement`, rating constants and types                |
+| `.../testimonial`    | `sp-testimonial`    | `defineSpectreTestimonial`, `SpectreTestimonialElement`, testimonial constants and types |
+| `.../alert`          | `sp-alert`          | `defineSpectreAlert`, `SpectreAlertElement`, alert constants and types                   |
+| `.../avatar`         | `sp-avatar`         | `defineSpectreAvatar`, `SpectreAvatarElement`, avatar constants and types                |
+| `.../spinner`        | `sp-spinner`        | `defineSpectreSpinner`, `SpectreSpinnerElement`, spinner constants and types             |
+| `.../tag`            | `sp-tag`            | `defineSpectreTag`, `SpectreTagElement`, tag constants and types                         |
+| `.../pricing-card`   | `sp-pricing-card`   | `defineSpectrePricingCard`, `SpectrePricingCardElement`, `SpectrePricingCardProps`       |
+| `.../container`      | `sp-container`      | `defineSpectreContainer`, `SpectreContainerElement`, container constants and types       |
+| `.../grid`           | `sp-grid`           | `defineSpectreGrid`, `SpectreGridElement`, grid constants and types                      |
+| `.../section`        | `sp-section`        | `defineSpectreSection`, `SpectreSectionElement`, `SpectreSectionProps`                   |
+| `.../stack`          | `sp-stack`          | `defineSpectreStack`, `SpectreStackElement`, stack constants and types                   |
+| `.../nav`            | `sp-nav`            | `defineSpectreNav`, `SpectreNavElement`, `SpectreNavProps`                               |
+| `.../nav-item`       | `sp-nav-item`       | `defineSpectreNavItem`, `SpectreNavItemElement`, `SpectreNavItemProps`                   |
+| `.../sidebar`        | `sp-sidebar`        | `defineSpectreSidebar`, `SpectreSidebarElement`, `SpectreSidebarProps`                   |
+| `.../sidebar-toggle` | `sp-sidebar-toggle` | `defineSpectreSidebarToggle`, `SpectreSidebarToggleElement`, `SpectreSidebarToggleProps` |
+| `.../dropdown`       | `sp-dropdown`       | `defineSpectreDropdown`, `SpectreDropdownElement`, dropdown constants and types          |
+| `.../footer`         | `sp-footer`         | `defineSpectreFooter`, `SpectreFooterElement`, `SpectreFooterProps`                      |
+| `.../modal`          | `sp-modal`          | `defineSpectreModal`, `SpectreModalElement`, `SpectreModalProps`                         |
+| `.../toast`          | `sp-toast`          | `defineSpectreToast`, `SpectreToastElement`, toast constants and types                   |
+| `.../tooltip`        | `sp-tooltip`        | `defineSpectreTooltip`, `SpectreTooltipElement`, tooltip constants and types             |
 
 Size constants are shared between input, textarea, and select. Import
 `spectreInputSizes` / `SpectreInputSize` from `.../input` when needed alongside
@@ -1303,14 +1405,14 @@ pass.
 ## AI And Automation Boundaries
 
 Claude Code (`claude-sonnet-4-6`) is the primary development agent for this
-repository. Codex handles releases, including cutting tagged releases and
-GitHub Releases, and production stabilization. Jules handles small automated
-fixes and dependency updates. GitHub Copilot provides development support.
-
-All AI agents with repository access (Claude Code, Codex, Copilot, Jules)
-have commit, push, and tag authority in this repository. Publishing to npm
-remains Bradley Potts's sole authority. See [AGENTS.md](AGENTS.md) for the
-full commit-policy and release-authority grant.
+repository. Codex handles releases, including cutting tagged releases and GitHub
+Releases, and production stabilization. Jules handles small automated fixes and
+dependency updates. GitHub Copilot provides development support.
+
+All AI agents with repository access (Claude Code, Codex, Copilot, Jules) have
+commit, push, and tag authority in this repository. Publishing to npm remains
+Bradley Potts's sole authority. See [AGENTS.md](AGENTS.md) for the full
+commit-policy and release-authority grant.
 
 **Protected from automated change:** component public API surface (tags,
 properties, events, slots, ARIA), the light-DOM rendering model, and the