@phcdevworks/spectre-components 1.4.0 → 1.6.0

package/README.md

@@ -1,5 +1,37 @@
 # @phcdevworks/spectre-components
 
+## Repository Snapshot
+
+| Field                  | Value                               |
+| ---------------------- | ----------------------------------- |
+| Project team           | `project-design`                    |
+| Repository role        | Spectre L3a Lit web component layer |
+| Package/artifact       | `@phcdevworks/spectre-components`   |
+| Current version/status | 1.6.0                               |
+
+## Standard Workflow
+
+1. Read [AGENTS.md](AGENTS.md), then the agent-specific guide for the task.
+2. Check [TODO.md](TODO.md) and [ROADMAP.md](ROADMAP.md) for current scope.
+3. Make the smallest repo-local change that satisfies the task.
+4. Run `npm run check` when validation is required or practical.
+5. Update docs and [CHANGELOG.md](CHANGELOG.md) only when behavior, public
+   contracts, or release-relevant metadata changed.
+
+## Documentation Map
+
+| Guide       | Path                         |
+| ----------- | ---------------------------- |
+| Agent rules | [AGENTS.md](AGENTS.md)       |
+| Claude Code | [CLAUDE.md](CLAUDE.md)       |
+| Codex       | [CODEX.md](CODEX.md)         |
+| Copilot     | [COPILOT.md](COPILOT.md)     |
+| Jules       | [JULES.md](JULES.md)         |
+| Roadmap     | [ROADMAP.md](ROADMAP.md)     |
+| Todo        | [TODO.md](TODO.md)           |
+| Changelog   | [CHANGELOG.md](CHANGELOG.md) |
+| Security    | [SECURITY.md](SECURITY.md)   |
+
 [![npm version](https://img.shields.io/npm/v/@phcdevworks/spectre-components)](https://www.npmjs.com/package/@phcdevworks/spectre-components)
 [![CI](https://github.com/phcdevworks/spectre-components/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/phcdevworks/spectre-components/actions/workflows/ci.yml)
 [![License](https://img.shields.io/npm/l/@phcdevworks/spectre-components)](LICENSE)
@@ -627,6 +659,203 @@ recipe.
 
 **Internal target** — `[data-sp-testimonial-native]` selects the native `<div>`.
 
+---
+
+### sp-alert
+
+Renders a `<div role="alert">` display primitive backed by the Spectre alert
+recipe.
+
+**Attributes**
+
+| Attribute                 | Type                                              | Default | Description                     |
+| ------------------------- | ------------------------------------------------- | ------- | ------------------------------- |
+| `variant`                 | `info \| success \| warning \| danger \| neutral` | `info`  | Visual style                    |
+| `size`                    | `sm \| md \| lg`                                  | `md`    | Alert size                      |
+| `dismissed`               | boolean                                           | `false` | Dismissed visual state          |
+| `disabled`                | boolean                                           | `false` | Disabled visual state           |
+| `loading`                 | boolean                                           | `false` | Busy visual state               |
+| `full-width`              | boolean                                           | `false` | Spans full container width      |
+| `id` / `title` / `aria-*` | string                                            | —       | Forwarded to the native `<div>` |
+
+**Content projection** — children become the alert content.
+
+**Accessibility** — renders `role="alert"` and reflects the `loading` state to
+`aria-busy`.
+
+**Internal target** — `[data-sp-alert-native]` selects the native `<div>`.
+
+---
+
+### sp-avatar
+
+Renders a `<div>` avatar container backed by the Spectre avatar recipe.
+
+**Attributes**
+
+| Attribute                 | Type                         | Default  | Description                      |
+| ------------------------- | ---------------------------- | -------- | -------------------------------- |
+| `size`                    | `xs \| sm \| md \| lg \| xl` | `md`     | Avatar size                      |
+| `shape`                   | `circle \| square`           | `circle` | Avatar shape                     |
+| `interactive`             | boolean                      | `false`  | Applies interactive styling      |
+| `disabled`                | boolean                      | `false`  | Disabled visual state            |
+| `loading`                 | boolean                      | `false`  | Busy visual state                |
+| `full-width`              | boolean                      | `false`  | Spans full container width       |
+| `placeholder`             | boolean                      | `false`  | Placeholder background and color |
+| `id` / `title` / `aria-*` | string                       | —        | Forwarded to the native `<div>`  |
+
+**Content projection** — children become the avatar content (an `<img>`,
+initials, or an icon).
+
+**Accessibility** — reflects the `loading` state to `aria-busy`.
+
+**Internal target** — `[data-sp-avatar-native]` selects the native `<div>`.
+
+---
+
+### sp-spinner
+
+Renders a `<div role="status">` loading indicator backed by the Spectre spinner
+recipe.
+
+**Attributes**
+
+| Attribute                 | Type                                                                                       | Default | Description                     |
+| ------------------------- | ------------------------------------------------------------------------------------------ | ------- | ------------------------------- |
+| `variant`                 | `primary \| secondary \| success \| warning \| danger \| info \| neutral \| accent \| cta` | —       | Arc color                       |
+| `size`                    | `sm \| md \| lg`                                                                           | `md`    | Spinner size                    |
+| `disabled`                | boolean                                                                                    | `false` | Disabled visual state           |
+| `loading`                 | boolean                                                                                    | `true`  | Busy visual state               |
+| `id` / `title` / `aria-*` | string                                                                                     | —       | Forwarded to the native `<div>` |
+
+**Accessibility** — renders `role="status"` and reflects the `loading` state to
+`aria-busy`. Defaults `aria-label` to `Loading` unless `aria-label` is provided.
+
+**Internal target** — `[data-sp-spinner-native]` selects the native `<div>`.
+
+---
+
+### sp-tag
+
+Renders a `<span>` tag/chip backed by the Spectre tag recipe.
+
+**Attributes**
+
+| Attribute                 | Type                                                                                                                      | Default   | Description                       |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------- | --------------------------------- |
+| `variant`                 | `default \| primary \| secondary \| success \| warning \| danger \| info \| neutral \| accent \| cta \| outline \| ghost` | `default` | Tag color                         |
+| `size`                    | `sm \| md \| lg`                                                                                                          | `md`      | Tag size                          |
+| `interactive`             | boolean                                                                                                                   | `false`   | Applies interactive styling       |
+| `selected`                | boolean                                                                                                                   | `false`   | Selected/active visual state      |
+| `dismissible`             | boolean                                                                                                                   | `false`   | Reserves space for a dismiss icon |
+| `disabled`                | boolean                                                                                                                   | `false`   | Disabled visual state             |
+| `loading`                 | boolean                                                                                                                   | `false`   | Busy visual state                 |
+| `full-width`              | boolean                                                                                                                   | `false`   | Spans full container width        |
+| `id` / `title` / `aria-*` | string                                                                                                                    | —         | Forwarded to the native `<span>`  |
+
+**Content projection** — children become the tag label (and any projected
+dismiss icon).
+
+**Accessibility** — reflects the `loading` state to `aria-busy`.
+
+**Internal target** — `[data-sp-tag-native]` selects the native `<span>`.
+
+---
+
+### sp-pricing-card
+
+Renders a `<div>` pricing card container backed by the Spectre pricing-card
+recipe.
+
+**Attributes**
+
+| Attribute                 | Type    | Default | Description                     |
+| ------------------------- | ------- | ------- | ------------------------------- |
+| `featured`                | boolean | `false` | Highlights the card as featured |
+| `interactive`             | boolean | `false` | Applies interactive styling     |
+| `disabled`                | boolean | `false` | Disabled visual state           |
+| `loading`                 | boolean | `false` | Busy visual state               |
+| `full-height`             | boolean | `false` | Spans full container height     |
+| `id` / `title` / `aria-*` | string  | —       | Forwarded to the native `<div>` |
+
+**Content projection** — children become the pricing card content (heading,
+price, feature list, call-to-action, etc.).
+
+**Accessibility** — reflects the `loading` state to `aria-busy`.
+
+**Internal target** — `[data-sp-pricing-card-native]` selects the native
+`<div>`.
+
+---
+
+### 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>`   |
+
+**Content projection** — children become the container content.
+
+**Internal target** — `[data-sp-container-native]` selects the native `<div>`.
+
+---
+
+### sp-grid
+
+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>` |
+
+**Content projection** — children become grid items.
+
+**Internal target** — `[data-sp-grid-native]` selects the native `<div>`.
+
+---
+
+### sp-section
+
+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>` |
+
+**Content projection** — children become the section content.
+
+**Internal target** — `[data-sp-section-native]` selects the native `<section>`.
+
+---
+
+### sp-stack
+
+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>`       |
+
+**Content projection** — children become stack items.
+
+**Internal target** — `[data-sp-stack-native]` selects the native `<div>`.
+
 ## Package exports / API surface
 
 ### Root — `@phcdevworks/spectre-components`
@@ -646,13 +875,19 @@ defineSpectreComponents() // registers all sp-* elements
 `defineSpectreSelect`, `defineSpectreCheckbox`, `defineSpectreRadio`,
 `defineSpectreLabel`, `defineSpectreFieldset`, `defineSpectreBadge`,
 `defineSpectreCard`, `defineSpectreIconBox`, `defineSpectreRating`,
-`defineSpectreTestimonial`
+`defineSpectreTestimonial`, `defineSpectreAlert`, `defineSpectreAvatar`,
+`defineSpectreSpinner`, `defineSpectreTag`, `defineSpectrePricingCard`,
+`defineSpectreContainer`, `defineSpectreGrid`, `defineSpectreSection`,
+`defineSpectreStack`
 
 **Element classes**: `SpectreButtonElement`, `SpectreInputElement`,
 `SpectreTextareaElement`, `SpectreSelectElement`, `SpectreCheckboxElement`,
 `SpectreRadioElement`, `SpectreLabelElement`, `SpectreFieldsetElement`,
 `SpectreBadgeElement`, `SpectreCardElement`, `SpectreIconBoxElement`,
-`SpectreRatingElement`, `SpectreTestimonialElement`
+`SpectreRatingElement`, `SpectreTestimonialElement`, `SpectreAlertElement`,
+`SpectreAvatarElement`, `SpectreSpinnerElement`, `SpectreTagElement`,
+`SpectrePricingCardElement`, `SpectreContainerElement`, `SpectreGridElement`,
+`SpectreSectionElement`, `SpectreStackElement`
 
 **Button constants and types**: `spectreButtonVariants`, `spectreButtonSizes`,
 `spectreButtonTypes`, `SpectreButtonVariant`, `SpectreButtonSize`,
@@ -668,31 +903,54 @@ defineSpectreComponents() // registers all sp-* elements
 
 **Display constants and types**: `spectreBadgeVariants`, `spectreBadgeSizes`,
 `spectreCardVariants`, `spectreIconBoxVariants`, `spectreIconBoxSizes`,
-`spectreRatingSizes`, `spectreTestimonialVariants`, `SpectreBadgeVariant`,
-`SpectreBadgeSize`, `SpectreCardVariant`, `SpectreIconBoxVariant`,
-`SpectreIconBoxSize`, `SpectreRatingSize`, `SpectreTestimonialVariant`,
-`SpectreBadgeProps`, `SpectreCardProps`, `SpectreIconBoxProps`,
-`SpectreRatingProps`, `SpectreTestimonialProps`
+`spectreRatingSizes`, `spectreTestimonialVariants`, `spectreAlertVariants`,
+`spectreAlertSizes`, `spectreAvatarShapes`, `spectreAvatarSizes`,
+`spectreSpinnerVariants`, `spectreSpinnerSizes`, `spectreTagVariants`,
+`spectreTagSizes`, `SpectreBadgeVariant`, `SpectreBadgeSize`,
+`SpectreCardVariant`, `SpectreIconBoxVariant`, `SpectreIconBoxSize`,
+`SpectreRatingSize`, `SpectreTestimonialVariant`, `SpectreAlertVariant`,
+`SpectreAlertSize`, `SpectreAvatarShape`, `SpectreAvatarSize`,
+`SpectreSpinnerVariant`, `SpectreSpinnerSize`, `SpectreTagVariant`,
+`SpectreTagSize`, `SpectreBadgeProps`, `SpectreCardProps`,
+`SpectreIconBoxProps`, `SpectreRatingProps`, `SpectreTestimonialProps`,
+`SpectreAlertProps`, `SpectreAvatarProps`, `SpectreSpinnerProps`,
+`SpectreTagProps`, `SpectrePricingCardProps`
+
+**Layout constants and types**: `spectreContainerMaxWidths`,
+`spectreGridColumns`, `spectreGridGaps`, `spectreStackAligns`,
+`spectreStackBases`, `spectreStackDirections`, `SpectreContainerMaxWidth`,
+`SpectreGridColumns`, `SpectreGridGap`, `SpectreStackAlign`,
+`SpectreStackBasis`, `SpectreStackDirection`, `SpectreContainerProps`,
+`SpectreGridProps`, `SpectreSectionProps`, `SpectreStackProps`
 
 ### 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 |
+| 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                   |
 
 Size constants are shared between input, textarea, and select. Import
 `spectreInputSizes` / `SpectreInputSize` from `.../input` when needed alongside