@warp-ds/elements 2.10.0-next.1 → 2.10.0-next.2

package/dist/custom-elements.json

@@ -2235,6 +2235,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Whether the card is visually selected.\n\nUse this when the card represents a selected item or choice. This only controls the visual selected state; update it from your application state when the selection changes.",
               "attribute": "selected",
               "reflects": true
             },
@@ -2245,6 +2246,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Whether the card uses the flat visual treatment.\n\nFlat cards use a bordered surface instead of the default elevated surface. Use this for denser layouts or when the card sits inside another surface.",
               "attribute": "flat"
             },
             {
@@ -2254,6 +2256,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Whether the whole card is interactive.\n\nWhen set, the card becomes keyboard focusable and Enter or Space triggers a click on the card. Use this only when the whole card has one action or represents one selectable choice.",
               "attribute": "clickable"
             },
             {
@@ -2283,6 +2286,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Whether the card is visually selected.\n\nUse this when the card represents a selected item or choice. This only controls the visual selected state; update it from your application state when the selection changes.",
               "fieldName": "selected"
             },
             {
@@ -2291,6 +2295,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Whether the card uses the flat visual treatment.\n\nFlat cards use a bordered surface instead of the default elevated surface. Use this for denser layouts or when the card sits inside another surface.",
               "fieldName": "flat"
             },
             {
@@ -2299,6 +2304,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Whether the whole card is interactive.\n\nWhen set, the card becomes keyboard focusable and Enter or Space triggers a click on the card. Use this only when the whole card has one action or represents one selectable choice.",
               "fieldName": "clickable"
             }
           ],

package/dist/docs/card/accessibility.md

@@ -1 +1,75 @@
 ## Accessibility
+
+Card is a visual container. It does not create a heading, landmark, list item, link, button, or other semantic structure for the slotted content.
+
+### Provide Semantic Content
+
+Use semantic HTML inside the card so assistive technologies can understand the content.
+
+```html
+<w-card>
+  <article style="padding: 16px;" aria-labelledby="listing-heading">
+    <h3 id="listing-heading">Apartment in Oslo</h3>
+    <p>Bright 3-room apartment with balcony.</p>
+  </article>
+</w-card>
+```
+
+Do not rely on the card surface, border, or selected styling to communicate meaning.
+
+### Selected State
+
+Use `selected` only when the card represents a selected item or choice.
+
+```html
+<w-card selected>
+  <div style="padding: 16px;">
+    <h3>Standard delivery</h3>
+    <p>Delivered in 2-4 business days.</p>
+  </div>
+</w-card>
+```
+
+The selected state should also be clear from the surrounding context, such as a group label, heading, or visible text.
+
+### Clickable Cards
+
+Use `clickable` only when the whole card has one action or represents one selectable choice.
+
+```html
+<w-card clickable>
+  <div style="padding: 16px;">
+    <h3>Home delivery</h3>
+    <p>Delivered to your door.</p>
+  </div>
+</w-card>
+```
+
+The visible card content should describe what will be selected or activated. Do not put separate links, buttons, form controls, or other interactive elements inside a clickable card.
+
+### Prefer Specific Interactive Elements
+
+If only part of the card is interactive, use the appropriate element for that action.
+
+Use a link for navigation:
+
+```html
+<w-card>
+  <div style="padding: 16px;">
+    <h3><a href="/listings/123">Apartment in Oslo</a></h3>
+    <p>Bright 3-room apartment with balcony.</p>
+  </div>
+</w-card>
+```
+
+Use a button for an action on the current page:
+
+```html
+<w-card>
+  <div style="padding: 16px;">
+    <h3>Apartment in Oslo</h3>
+    <p>Bright 3-room apartment with balcony.</p>
+    <w-button variant="primary">Contact seller</w-button>
+  </div>
+</w-card>
+```

package/dist/docs/card/api.md

@@ -7,9 +7,9 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 | Name | Type | Default | Summary |
 |-|-|-|-|
 | buttonText (JS only) | `unknown` | `-` | - |
-| clickable | `boolean` | `false` | - |
-| flat | `boolean` | `false` | - |
-| selected | `boolean` | `false` | - |
+| clickable | `boolean` | `false` | Whether the whole card is interactive. |
+| flat | `boolean` | `false` | Whether the card uses the flat visual treatment. |
+| selected | `boolean` | `false` | Whether the card is visually selected. |
 
 ### Property Details
 
@@ -22,21 +22,27 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 #### clickable
 
+Whether the whole card is interactive.
 
+When set, the card becomes keyboard focusable and Enter or Space triggers a click on the card. Use this only when the whole card has one action or represents one selectable choice.
 
 - Type: `boolean`
 - Default: `false`
 
 #### flat
 
+Whether the card uses the flat visual treatment.
 
+Flat cards use a bordered surface instead of the default elevated surface. Use this for denser layouts or when the card sits inside another surface.
 
 - Type: `boolean`
 - Default: `false`
 
 #### selected
 
+Whether the card is visually selected.
 
+Use this when the card represents a selected item or choice. This only controls the visual selected state; update it from your application state when the selection changes.
 
 - Type: `boolean`
 - Default: `false`

package/dist/docs/card/card.md

@@ -8,10 +8,235 @@ Card is a layout component used for separating content areas on a page.
 
 ## Usage
 
+Card is a layout component for visually grouping related content as one item.
+
+Use `w-card` for listings, summaries, recommendations, or selectable choices where the grouped content should feel like a single object. The component does not add padding, headings, spacing between children, or semantic structure. Those must be provided by the content inside the card.
+
+### Basic Card
+
+```html
+<w-card>
+  <div style="padding: 16px;">
+    <h3>Apartment in Oslo</h3>
+    <p>Bright 3-room apartment with balcony.</p>
+  </div>
+</w-card>
+```
+
+### Visual Treatments
+
+The default card uses an elevated surface. Use `flat` when the card should sit more quietly in the layout.
+
+```html
+<w-card>
+  <div style="padding: 16px;">
+    <h3>Elevated card</h3>
+    <p>Use this for cards that need more visual separation.</p>
+  </div>
+</w-card>
+
+<w-card flat>
+  <div style="padding: 16px;">
+    <h3>Flat card</h3>
+    <p>Use this for dense layouts or cards inside another surface.</p>
+  </div>
+</w-card>
+```
+
+### Selected Cards
+
+Use `selected` when a card represents a selected item or choice.
+
+```html
+<w-card selected>
+  <div style="padding: 16px;">
+    <h3>Standard delivery</h3>
+    <p>Delivered in 2-4 business days.</p>
+  </div>
+</w-card>
+```
+
+The `selected` property only controls the card's visual state. Update it from your application state when the selection changes.
+
+### Clickable Cards
+
+Use `clickable` when the whole card should behave as one interactive choice. The card becomes keyboard focusable, and Enter or Space triggers a click on the card.
+
+```html
+<w-card clickable>
+  <div style="padding: 16px;">
+    <h3>Pick up nearby</h3>
+    <p>Collect the item from a pickup point.</p>
+  </div>
+</w-card>
+```
+
+Listen for the card's click event and update `selected` yourself.
+
+```html
+<w-card clickable selected>
+  <div style="padding: 16px;">
+    <h3>Home delivery</h3>
+    <p>Delivered to your door.</p>
+  </div>
+</w-card>
+```
+
+Do not use `clickable` when the card contains separate links, buttons, form controls, or other interactive elements. In those cases, keep the card non-clickable and make the specific control interactive instead.
+
 ## Accessibility
 
+Card is a visual container. It does not create a heading, landmark, list item, link, button, or other semantic structure for the slotted content.
+
+### Provide Semantic Content
+
+Use semantic HTML inside the card so assistive technologies can understand the content.
+
+```html
+<w-card>
+  <article style="padding: 16px;" aria-labelledby="listing-heading">
+    <h3 id="listing-heading">Apartment in Oslo</h3>
+    <p>Bright 3-room apartment with balcony.</p>
+  </article>
+</w-card>
+```
+
+Do not rely on the card surface, border, or selected styling to communicate meaning.
+
+### Selected State
+
+Use `selected` only when the card represents a selected item or choice.
+
+```html
+<w-card selected>
+  <div style="padding: 16px;">
+    <h3>Standard delivery</h3>
+    <p>Delivered in 2-4 business days.</p>
+  </div>
+</w-card>
+```
+
+The selected state should also be clear from the surrounding context, such as a group label, heading, or visible text.
+
+### Clickable Cards
+
+Use `clickable` only when the whole card has one action or represents one selectable choice.
+
+```html
+<w-card clickable>
+  <div style="padding: 16px;">
+    <h3>Home delivery</h3>
+    <p>Delivered to your door.</p>
+  </div>
+</w-card>
+```
+
+The visible card content should describe what will be selected or activated. Do not put separate links, buttons, form controls, or other interactive elements inside a clickable card.
+
+### Prefer Specific Interactive Elements
+
+If only part of the card is interactive, use the appropriate element for that action.
+
+Use a link for navigation:
+
+```html
+<w-card>
+  <div style="padding: 16px;">
+    <h3><a href="/listings/123">Apartment in Oslo</a></h3>
+    <p>Bright 3-room apartment with balcony.</p>
+  </div>
+</w-card>
+```
+
+Use a button for an action on the current page:
+
+```html
+<w-card>
+  <div style="padding: 16px;">
+    <h3>Apartment in Oslo</h3>
+    <p>Bright 3-room apartment with balcony.</p>
+    <w-button variant="primary">Contact seller</w-button>
+  </div>
+</w-card>
+```
+
 ## Examples
 
+### Basic
+
+<elements-example>
+
+```html
+<w-card>
+  <div style="padding: 16px;">
+    <h3>Apartment in Oslo</h3>
+    <p>Bright 3-room apartment with balcony.</p>
+  </div>
+</w-card>
+```
+
+</elements-example>
+
+### Flat
+
+<elements-example>
+
+```html
+<w-card flat>
+  <div style="padding: 16px;">
+    <h3>Order summary</h3>
+    <p>Review the item price, delivery, and total before continuing.</p>
+  </div>
+</w-card>
+```
+
+</elements-example>
+
+### Selected
+
+<elements-example>
+
+```html
+<w-card selected>
+  <div style="padding: 16px;">
+    <h3>Standard delivery</h3>
+    <p>Delivered in 2-4 business days.</p>
+  </div>
+</w-card>
+```
+
+</elements-example>
+
+### Flat Selected
+
+<elements-example>
+
+```html
+<w-card flat selected>
+  <div style="padding: 16px;">
+    <h3>Pickup point</h3>
+    <p>Collect the item from a nearby pickup point.</p>
+  </div>
+</w-card>
+```
+
+</elements-example>
+
+### Clickable
+
+<elements-example>
+
+```html
+<w-card clickable>
+  <div style="padding: 16px;">
+    <h3>Home delivery</h3>
+    <p>Delivered to your door.</p>
+  </div>
+</w-card>
+```
+
+</elements-example>
+
 ## `<w-card>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
@@ -21,9 +246,9 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 | Name | Type | Default | Summary |
 |-|-|-|-|
 | buttonText (JS only) | `unknown` | `-` | - |
-| clickable | `boolean` | `false` | - |
-| flat | `boolean` | `false` | - |
-| selected | `boolean` | `false` | - |
+| clickable | `boolean` | `false` | Whether the whole card is interactive. |
+| flat | `boolean` | `false` | Whether the card uses the flat visual treatment. |
+| selected | `boolean` | `false` | Whether the card is visually selected. |
 
 ### Property Details
 
@@ -36,21 +261,27 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 #### clickable
 
+Whether the whole card is interactive.
 
+When set, the card becomes keyboard focusable and Enter or Space triggers a click on the card. Use this only when the whole card has one action or represents one selectable choice.
 
 - Type: `boolean`
 - Default: `false`
 
 #### flat
 
+Whether the card uses the flat visual treatment.
 
+Flat cards use a bordered surface instead of the default elevated surface. Use this for denser layouts or when the card sits inside another surface.
 
 - Type: `boolean`
 - Default: `false`
 
 #### selected
 
+Whether the card is visually selected.
 
+Use this when the card represents a selected item or choice. This only controls the visual selected state; update it from your application state when the selection changes.
 
 - Type: `boolean`
 - Default: `false`

package/dist/docs/card/examples.md

@@ -1 +1,76 @@
 ## Examples
+
+### Basic
+
+<elements-example>
+
+```html
+<w-card>
+  <div style="padding: 16px;">
+    <h3>Apartment in Oslo</h3>
+    <p>Bright 3-room apartment with balcony.</p>
+  </div>
+</w-card>
+```
+
+</elements-example>
+
+### Flat
+
+<elements-example>
+
+```html
+<w-card flat>
+  <div style="padding: 16px;">
+    <h3>Order summary</h3>
+    <p>Review the item price, delivery, and total before continuing.</p>
+  </div>
+</w-card>
+```
+
+</elements-example>
+
+### Selected
+
+<elements-example>
+
+```html
+<w-card selected>
+  <div style="padding: 16px;">
+    <h3>Standard delivery</h3>
+    <p>Delivered in 2-4 business days.</p>
+  </div>
+</w-card>
+```
+
+</elements-example>
+
+### Flat Selected
+
+<elements-example>
+
+```html
+<w-card flat selected>
+  <div style="padding: 16px;">
+    <h3>Pickup point</h3>
+    <p>Collect the item from a nearby pickup point.</p>
+  </div>
+</w-card>
+```
+
+</elements-example>
+
+### Clickable
+
+<elements-example>
+
+```html
+<w-card clickable>
+  <div style="padding: 16px;">
+    <h3>Home delivery</h3>
+    <p>Delivered to your door.</p>
+  </div>
+</w-card>
+```
+
+</elements-example>

package/dist/docs/card/usage.md

@@ -1 +1,77 @@
 ## Usage
+
+Card is a layout component for visually grouping related content as one item.
+
+Use `w-card` for listings, summaries, recommendations, or selectable choices where the grouped content should feel like a single object. The component does not add padding, headings, spacing between children, or semantic structure. Those must be provided by the content inside the card.
+
+### Basic Card
+
+```html
+<w-card>
+  <div style="padding: 16px;">
+    <h3>Apartment in Oslo</h3>
+    <p>Bright 3-room apartment with balcony.</p>
+  </div>
+</w-card>
+```
+
+### Visual Treatments
+
+The default card uses an elevated surface. Use `flat` when the card should sit more quietly in the layout.
+
+```html
+<w-card>
+  <div style="padding: 16px;">
+    <h3>Elevated card</h3>
+    <p>Use this for cards that need more visual separation.</p>
+  </div>
+</w-card>
+
+<w-card flat>
+  <div style="padding: 16px;">
+    <h3>Flat card</h3>
+    <p>Use this for dense layouts or cards inside another surface.</p>
+  </div>
+</w-card>
+```
+
+### Selected Cards
+
+Use `selected` when a card represents a selected item or choice.
+
+```html
+<w-card selected>
+  <div style="padding: 16px;">
+    <h3>Standard delivery</h3>
+    <p>Delivered in 2-4 business days.</p>
+  </div>
+</w-card>
+```
+
+The `selected` property only controls the card's visual state. Update it from your application state when the selection changes.
+
+### Clickable Cards
+
+Use `clickable` when the whole card should behave as one interactive choice. The card becomes keyboard focusable, and Enter or Space triggers a click on the card.
+
+```html
+<w-card clickable>
+  <div style="padding: 16px;">
+    <h3>Pick up nearby</h3>
+    <p>Collect the item from a pickup point.</p>
+  </div>
+</w-card>
+```
+
+Listen for the card's click event and update `selected` yourself.
+
+```html
+<w-card clickable selected>
+  <div style="padding: 16px;">
+    <h3>Home delivery</h3>
+    <p>Delivered to your door.</p>
+  </div>
+</w-card>
+```
+
+Do not use `clickable` when the card contains separate links, buttons, form controls, or other interactive elements. In those cases, keep the card non-clickable and make the specific control interactive instead.

package/dist/index.d.ts

@@ -723,22 +723,34 @@ Defaults to the localized "You are here" label. Set `aria-label` when the defaul
 };
 
 export type WarpCardProps = {
-  /**  */
+  /** Whether the card is visually selected.
+
+Use this when the card represents a selected item or choice. This only controls the visual selected state; update it from your application state when the selection changes. */
   selected?: WarpCard["selected"];
-  /**  */
+  /** Whether the card uses the flat visual treatment.
+
+Flat cards use a bordered surface instead of the default elevated surface. Use this for denser layouts or when the card sits inside another surface. */
   flat?: WarpCard["flat"];
-  /**  */
+  /** Whether the whole card is interactive.
+
+When set, the card becomes keyboard focusable and Enter or Space triggers a click on the card. Use this only when the whole card has one action or represents one selectable choice. */
   clickable?: WarpCard["clickable"];
   /**  */
   buttonText?: WarpCard["buttonText"];
 };
 
 export type WarpCardSolidJsProps = {
-  /**  */
+  /** Whether the card is visually selected.
+
+Use this when the card represents a selected item or choice. This only controls the visual selected state; update it from your application state when the selection changes. */
   "prop:selected"?: WarpCard["selected"];
-  /**  */
+  /** Whether the card uses the flat visual treatment.
+
+Flat cards use a bordered surface instead of the default elevated surface. Use this for denser layouts or when the card sits inside another surface. */
   "prop:flat"?: WarpCard["flat"];
-  /**  */
+  /** Whether the whole card is interactive.
+
+When set, the card becomes keyboard focusable and Enter or Space triggers a click on the card. Use this only when the whole card has one action or represents one selectable choice. */
   "prop:clickable"?: WarpCard["clickable"];
   /**  */
   "prop:buttonText"?: WarpCard["buttonText"];
@@ -2219,9 +2231,15 @@ export type CustomElements = {
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
-   * - `selected`: undefined
-   * - `flat`: undefined
-   * - `clickable`: undefined
+   * - `selected`: Whether the card is visually selected.
+   *
+   * Use this when the card represents a selected item or choice. This only controls the visual selected state; update it from your application state when the selection changes.
+   * - `flat`: Whether the card uses the flat visual treatment.
+   *
+   * Flat cards use a bordered surface instead of the default elevated surface. Use this for denser layouts or when the card sits inside another surface.
+   * - `clickable`: Whether the whole card is interactive.
+   *
+   * When set, the card becomes keyboard focusable and Enter or Space triggers a click on the card. Use this only when the whole card has one action or represents one selectable choice.
    * - `buttonText`: undefined (property only)
    *
    * ## Methods
@@ -3197,9 +3215,15 @@ export type CustomElementsSolidJs = {
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
-   * - `selected`: undefined
-   * - `flat`: undefined
-   * - `clickable`: undefined
+   * - `selected`: Whether the card is visually selected.
+   *
+   * Use this when the card represents a selected item or choice. This only controls the visual selected state; update it from your application state when the selection changes.
+   * - `flat`: Whether the card uses the flat visual treatment.
+   *
+   * Flat cards use a bordered surface instead of the default elevated surface. Use this for denser layouts or when the card sits inside another surface.
+   * - `clickable`: Whether the whole card is interactive.
+   *
+   * When set, the card becomes keyboard focusable and Enter or Space triggers a click on the card. Use this only when the whole card has one action or represents one selectable choice.
    * - `buttonText`: undefined (property only)
    *
    * ## Methods