@warp-ds/elements 2.9.0 → 2.9.1-next.1

package/dist/custom-elements.json

@@ -1918,6 +1918,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Makes the box bleed to the container edge.\nExtends the box into the horizontal gutter on narrow screens. Adds negative horizontal margins and square side corners below the small breakpoint, then restores the normal margins and rounded corners from the small breakpoint and up.",
               "attribute": "bleed",
               "reflects": true
             },
@@ -1928,6 +1929,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Shows the box as a bordered surface.\nUse this when the content needs a clear visual boundary from the surrounding page.",
               "attribute": "bordered",
               "reflects": true
             },
@@ -1938,6 +1940,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Shows the box with information styling.\nUse this for supporting informational content that should be visually separated from the surrounding page.",
               "attribute": "info",
               "reflects": true
             },
@@ -1948,6 +1951,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Shows the box with neutral styling.\nUse this for quiet grouped content that needs a background without strong emphasis.",
               "attribute": "neutral",
               "reflects": true
             },
@@ -1957,6 +1961,8 @@
               "type": {
                 "text": "string"
               },
+              "default": "'region'",
+              "description": "ARIA role for the box wrapper.\nDefaults to a role of `region`. Set `role=\"none\"` to override this behaviour for purely visual grouping, or set a specific role when the box has a clearer semantic purpose.",
               "attribute": "role",
               "reflects": true
             }
@@ -1968,6 +1974,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Makes the box bleed to the container edge.\nExtends the box into the horizontal gutter on narrow screens. Adds negative horizontal margins and square side corners below the small breakpoint, then restores the normal margins and rounded corners from the small breakpoint and up.",
               "fieldName": "bleed"
             },
             {
@@ -1976,6 +1983,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Shows the box as a bordered surface.\nUse this when the content needs a clear visual boundary from the surrounding page.",
               "fieldName": "bordered"
             },
             {
@@ -1984,6 +1992,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Shows the box with information styling.\nUse this for supporting informational content that should be visually separated from the surrounding page.",
               "fieldName": "info"
             },
             {
@@ -1992,6 +2001,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Shows the box with neutral styling.\nUse this for quiet grouped content that needs a background without strong emphasis.",
               "fieldName": "neutral"
             },
             {
@@ -1999,9 +2009,17 @@
               "type": {
                 "text": "string"
               },
+              "default": "'region'",
+              "description": "ARIA role for the box wrapper.\nDefaults to a role of `region`. Set `role=\"none\"` to override this behaviour for purely visual grouping, or set a specific role when the box has a clearer semantic purpose.",
               "fieldName": "role"
             }
           ],
+          "mixins": [
+            {
+              "name": "FormControlMixin",
+              "package": "@open-wc/form-control"
+            }
+          ],
           "superclass": {
             "name": "LitElement",
             "package": "lit"

package/dist/docs/box/accessibility.md

@@ -1 +1,30 @@
 ## Accessibility
+
+Box wraps its slotted content in a section tag by default which is equivalant to role="region" for the purposes of screen readers.
+
+### Do Not Rely On Visual Treatment Alone
+
+The `info`, `neutral`, `bordered`, and `bleed` properties are visual only. They do not change the meaning of the content for assistive technologies.
+
+Always use headings, text, and semantic HTML inside the box to communicate structure and purpose.
+
+### Landmark Behaviour For Meaningful Sections
+
+By default, w-box behaves as a landmark for screen readers. This means it represents a section of the page that users may want to navigate to directly.
+
+We strongly suggest you provide a heading and an accessible landmark name to ensure that screen readers properly treat it as a landmark.
+
+```html
+  <w-box aria-labelledby="delivery-heading">
+    <h2 id="delivery-heading">Delivery</h2>
+    <p>Choose how you want the item delivered.</p>
+  </w-box>
+```
+
+If you must use box for a purely visual grouping, set role none:
+
+```html
+<w-box role="none">
+  <p>This box is only a visual container.</p>
+</w-box>
+```

package/dist/docs/box/api.md

@@ -4,48 +4,53 @@
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| bleed | `boolean` | `false` | - |
-| bordered | `boolean` | `false` | - |
-| info | `boolean` | `false` | - |
-| neutral | `boolean` | `false` | - |
-| role | `string` | `-` | - |
+| bleed | `boolean` | `false` | Makes the box bleed to the container edge. |
+| bordered | `boolean` | `false` | Shows the box as a bordered surface. |
+| info | `boolean` | `false` | Shows the box with information styling. |
+| neutral | `boolean` | `false` | Shows the box with neutral styling. |
+| role | `string` | `'region'` | ARIA role for the box wrapper. |
 
 ### Property Details
 
 #### bleed
 
-
+Makes the box bleed to the container edge.
+Extends the box into the horizontal gutter on narrow screens. Adds negative horizontal margins and square side corners below the small breakpoint, then restores the normal margins and rounded corners from the small breakpoint and up.
 
 - Type: `boolean`
 - Default: `false`
 
 #### bordered
 
-
+Shows the box as a bordered surface.
+Use this when the content needs a clear visual boundary from the surrounding page.
 
 - Type: `boolean`
 - Default: `false`
 
 #### info
 
-
+Shows the box with information styling.
+Use this for supporting informational content that should be visually separated from the surrounding page.
 
 - Type: `boolean`
 - Default: `false`
 
 #### neutral
 
-
+Shows the box with neutral styling.
+Use this for quiet grouped content that needs a background without strong emphasis.
 
 - Type: `boolean`
 - Default: `false`
 
 #### role
 
-
+ARIA role for the box wrapper.
+Defaults to a role of `region`. Set `role="none"` to override this behaviour for purely visual grouping, or set a specific role when the box has a clearer semantic purpose.
 
 - Type: `string`
-- Default: `-`
+- Default: `'region'`
 
 ### Types
 

package/dist/docs/box/box.md

@@ -8,58 +8,236 @@ Box is a layout component used for separating content areas on a page.
 
 ## Usage
 
+Box is a layout component for visually separating a section of content from the surrounding page.
+
+Use `w-box` for grouped content that needs padding, a background, or a border. The component does not add heading structure, spacing between children, or interactive behavior. Those you must provide yourself.
+
+### Basic Box
+
+```html
+<w-box aria-labelledby="delivery-heading">
+  <h2 id="deliver-heading">Delivery</h2>
+  <p>Choose how you want the item delivered.</p>
+</w-box>
+```
+
+### Visual Treatments
+
+Use one visual treatment at a time:
+
+- `neutral`: a quiet sunken surface for grouped content
+- `info`: a subtle information background
+- `bordered`: a bordered surface with the default background
+
+```html
+<w-box neutral role="none">
+  <p>Neutral content area</p>
+</w-box>
+
+<w-box info role="none">
+  <p>Informational content area</p>
+</w-box>
+
+<w-box bordered role="none">
+  <p>Bordered content area</p>
+</w-box>
+```
+
+### Bleed
+
+Use `bleed` when a box sits inside a page gutter but should extend to the container edge on narrow screens. `bleed` is commonly combined with a visual treatment such as `neutral` or `info`.
+
+```html
+<w-box neutral bleed aria-labelledby="summary-heading">
+  <h2 id="summary-heading">Summary</h2>
+  <p>This box extends into the horizontal gutter on narrow screens.</p>
+</w-box>
+```
+
 ## Accessibility
 
+Box wraps its slotted content in a section tag by default which is equivalant to role="region" for the purposes of screen readers.
+
+### Do Not Rely On Visual Treatment Alone
+
+The `info`, `neutral`, `bordered`, and `bleed` properties are visual only. They do not change the meaning of the content for assistive technologies.
+
+Always use headings, text, and semantic HTML inside the box to communicate structure and purpose.
+
+### Landmark Behaviour For Meaningful Sections
+
+By default, w-box behaves as a landmark for screen readers. This means it represents a section of the page that users may want to navigate to directly.
+
+We strongly suggest you provide a heading and an accessible landmark name to ensure that screen readers properly treat it as a landmark.
+
+```html
+  <w-box aria-labelledby="delivery-heading">
+    <h2 id="delivery-heading">Delivery</h2>
+    <p>Choose how you want the item delivered.</p>
+  </w-box>
+```
+
+If you must use box for a purely visual grouping, set role none:
+
+```html
+<w-box role="none">
+  <p>This box is only a visual container.</p>
+</w-box>
+```
+
 ## Examples
 
+### Basic
+
+<style-isolate>
+  <w-box aria-labelledby="delivery-heading">
+    <h2 id="delivery-heading">Delivery</h2>
+    <p>Choose how you want the item delivered.</p>
+  </w-box>
+</style-isolate>
+
+```html
+<w-box aria-labelledby="delivery-heading">
+  <h2 id="delivery-heading">Delivery</h2>
+  <p>Choose how you want the item delivered.</p>
+</w-box>
+```
+
+### Neutral
+
+<style-isolate>
+  <w-box neutral aria-labelledby="order-summary-heading">
+    <h2 id="order-summary-heading">Order summary</h2>
+    <p>Review the item price, delivery, and total before continuing.</p>
+  </w-box>
+</style-isolate>
+
+```html
+<w-box neutral aria-labelledby="order-summary-heading">
+  <h2 id="order-summary-heading">Order summary</h2>
+  <p>Review the item price, delivery, and total before continuing.</p>
+</w-box>
+```
+
+### Info
+
+<style-isolate>
+  <w-box info aria-labelledby="good-to-know-heading">
+    <h2 id="good-to-know-heading">Good to know</h2>
+    <p>You can change the delivery method before payment.</p>
+  </w-box>
+</style-isolate>
+
+```html
+<w-box info aria-labelledby="good-to-know-heading">
+  <h2 id="good-to-know-heading">Good to know</h2>
+  <p>You can change the delivery method before payment.</p>
+</w-box>
+```
+
+### Bordered
+
+<style-isolate>
+  <w-box bordered aria-labelledby="contact-seller-heading">
+    <h2 id="contact-seller-heading">Contact seller</h2>
+    <p>Send a message to ask about pickup times.</p>
+  </w-box>
+</style-isolate>
+
+```html
+<w-box bordered aria-labelledby="contact-seller-heading">
+  <h2 id="contact-seller-heading">Contact seller</h2>
+  <p>Send a message to ask about pickup times.</p>
+</w-box>
+```
+
+### Bleed
+
+<style-isolate>
+  <div style="padding: 0 16px;">
+    <w-box neutral bleed aria-labelledby="summary-heading">
+      <h2 id="summary-heading">Summary</h2>
+      <p>This box extends into the horizontal gutter on narrow screens.</p>
+    </w-box>
+  </div>
+</style-isolate>
+
+```html
+<div style="padding: 0 16px;">
+  <w-box neutral bleed aria-labelledby="summary-heading">
+    <h2 id="summary-heading">Summary</h2>
+    <p>This box extends into the horizontal gutter on narrow screens.</p>
+  </w-box>
+</div>
+```
+
+### Visual Grouping Without Accessibility Landmarking
+
+<style-isolate>
+  <w-box role="none">
+    <p>This box is only a visual container.</p>
+  </w-box>
+</style-isolate>
+
+```html
+<w-box role="none">
+  <p>This box is only a visual container.</p>
+</w-box>
+```
+
 ## API Documentation
 
 ### Properties
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| bleed | `boolean` | `false` | - |
-| bordered | `boolean` | `false` | - |
-| info | `boolean` | `false` | - |
-| neutral | `boolean` | `false` | - |
-| role | `string` | `-` | - |
+| bleed | `boolean` | `false` | Makes the box bleed to the container edge. |
+| bordered | `boolean` | `false` | Shows the box as a bordered surface. |
+| info | `boolean` | `false` | Shows the box with information styling. |
+| neutral | `boolean` | `false` | Shows the box with neutral styling. |
+| role | `string` | `'region'` | ARIA role for the box wrapper. |
 
 ### Property Details
 
 #### bleed
 
-
+Makes the box bleed to the container edge.
+Extends the box into the horizontal gutter on narrow screens. Adds negative horizontal margins and square side corners below the small breakpoint, then restores the normal margins and rounded corners from the small breakpoint and up.
 
 - Type: `boolean`
 - Default: `false`
 
 #### bordered
 
-
+Shows the box as a bordered surface.
+Use this when the content needs a clear visual boundary from the surrounding page.
 
 - Type: `boolean`
 - Default: `false`
 
 #### info
 
-
+Shows the box with information styling.
+Use this for supporting informational content that should be visually separated from the surrounding page.
 
 - Type: `boolean`
 - Default: `false`
 
 #### neutral
 
-
+Shows the box with neutral styling.
+Use this for quiet grouped content that needs a background without strong emphasis.
 
 - Type: `boolean`
 - Default: `false`
 
 #### role
 
-
+ARIA role for the box wrapper.
+Defaults to a role of `region`. Set `role="none"` to override this behaviour for purely visual grouping, or set a specific role when the box has a clearer semantic purpose.
 
 - Type: `string`
-- Default: `-`
+- Default: `'region'`
 
 ### Types
 

package/dist/docs/box/examples.md

@@ -1 +1,99 @@
 ## Examples
+
+### Basic
+
+<style-isolate>
+  <w-box aria-labelledby="delivery-heading">
+    <h2 id="delivery-heading">Delivery</h2>
+    <p>Choose how you want the item delivered.</p>
+  </w-box>
+</style-isolate>
+
+```html
+<w-box aria-labelledby="delivery-heading">
+  <h2 id="delivery-heading">Delivery</h2>
+  <p>Choose how you want the item delivered.</p>
+</w-box>
+```
+
+### Neutral
+
+<style-isolate>
+  <w-box neutral aria-labelledby="order-summary-heading">
+    <h2 id="order-summary-heading">Order summary</h2>
+    <p>Review the item price, delivery, and total before continuing.</p>
+  </w-box>
+</style-isolate>
+
+```html
+<w-box neutral aria-labelledby="order-summary-heading">
+  <h2 id="order-summary-heading">Order summary</h2>
+  <p>Review the item price, delivery, and total before continuing.</p>
+</w-box>
+```
+
+### Info
+
+<style-isolate>
+  <w-box info aria-labelledby="good-to-know-heading">
+    <h2 id="good-to-know-heading">Good to know</h2>
+    <p>You can change the delivery method before payment.</p>
+  </w-box>
+</style-isolate>
+
+```html
+<w-box info aria-labelledby="good-to-know-heading">
+  <h2 id="good-to-know-heading">Good to know</h2>
+  <p>You can change the delivery method before payment.</p>
+</w-box>
+```
+
+### Bordered
+
+<style-isolate>
+  <w-box bordered aria-labelledby="contact-seller-heading">
+    <h2 id="contact-seller-heading">Contact seller</h2>
+    <p>Send a message to ask about pickup times.</p>
+  </w-box>
+</style-isolate>
+
+```html
+<w-box bordered aria-labelledby="contact-seller-heading">
+  <h2 id="contact-seller-heading">Contact seller</h2>
+  <p>Send a message to ask about pickup times.</p>
+</w-box>
+```
+
+### Bleed
+
+<style-isolate>
+  <div style="padding: 0 16px;">
+    <w-box neutral bleed aria-labelledby="summary-heading">
+      <h2 id="summary-heading">Summary</h2>
+      <p>This box extends into the horizontal gutter on narrow screens.</p>
+    </w-box>
+  </div>
+</style-isolate>
+
+```html
+<div style="padding: 0 16px;">
+  <w-box neutral bleed aria-labelledby="summary-heading">
+    <h2 id="summary-heading">Summary</h2>
+    <p>This box extends into the horizontal gutter on narrow screens.</p>
+  </w-box>
+</div>
+```
+
+### Visual Grouping Without Accessibility Landmarking
+
+<style-isolate>
+  <w-box role="none">
+    <p>This box is only a visual container.</p>
+  </w-box>
+</style-isolate>
+
+```html
+<w-box role="none">
+  <p>This box is only a visual container.</p>
+</w-box>
+```

package/dist/docs/box/usage.md

@@ -1 +1,48 @@
 ## Usage
+
+Box is a layout component for visually separating a section of content from the surrounding page.
+
+Use `w-box` for grouped content that needs padding, a background, or a border. The component does not add heading structure, spacing between children, or interactive behavior. Those you must provide yourself.
+
+### Basic Box
+
+```html
+<w-box aria-labelledby="delivery-heading">
+  <h2 id="deliver-heading">Delivery</h2>
+  <p>Choose how you want the item delivered.</p>
+</w-box>
+```
+
+### Visual Treatments
+
+Use one visual treatment at a time:
+
+- `neutral`: a quiet sunken surface for grouped content
+- `info`: a subtle information background
+- `bordered`: a bordered surface with the default background
+
+```html
+<w-box neutral role="none">
+  <p>Neutral content area</p>
+</w-box>
+
+<w-box info role="none">
+  <p>Informational content area</p>
+</w-box>
+
+<w-box bordered role="none">
+  <p>Bordered content area</p>
+</w-box>
+```
+
+### Bleed
+
+Use `bleed` when a box sits inside a page gutter but should extend to the container edge on narrow screens. `bleed` is commonly combined with a visual treatment such as `neutral` or `info`.
+
+```html
+<w-box neutral bleed aria-labelledby="summary-heading">
+  <h2 id="summary-heading">Summary</h2>
+  <p>This box extends into the horizontal gutter on narrow screens.</p>
+</w-box>
+```
+

package/dist/index.d.ts

@@ -616,28 +616,38 @@ Use this with a parent element that has `position: relative`. Accepted values ar
 };
 
 export type WarpBoxProps = {
-  /**  */
+  /** Makes the box bleed to the container edge.
+Extends the box into the horizontal gutter on narrow screens. Adds negative horizontal margins and square side corners below the small breakpoint, then restores the normal margins and rounded corners from the small breakpoint and up. */
   bleed?: WarpBox["bleed"];
-  /**  */
+  /** Shows the box as a bordered surface.
+Use this when the content needs a clear visual boundary from the surrounding page. */
   bordered?: WarpBox["bordered"];
-  /**  */
+  /** Shows the box with information styling.
+Use this for supporting informational content that should be visually separated from the surrounding page. */
   info?: WarpBox["info"];
-  /**  */
+  /** Shows the box with neutral styling.
+Use this for quiet grouped content that needs a background without strong emphasis. */
   neutral?: WarpBox["neutral"];
-  /**  */
+  /** ARIA role for the box wrapper.
+Defaults to a role of `region`. Set `role="none"` to override this behaviour for purely visual grouping, or set a specific role when the box has a clearer semantic purpose. */
   role?: WarpBox["role"];
 };
 
 export type WarpBoxSolidJsProps = {
-  /**  */
+  /** Makes the box bleed to the container edge.
+Extends the box into the horizontal gutter on narrow screens. Adds negative horizontal margins and square side corners below the small breakpoint, then restores the normal margins and rounded corners from the small breakpoint and up. */
   "prop:bleed"?: WarpBox["bleed"];
-  /**  */
+  /** Shows the box as a bordered surface.
+Use this when the content needs a clear visual boundary from the surrounding page. */
   "prop:bordered"?: WarpBox["bordered"];
-  /**  */
+  /** Shows the box with information styling.
+Use this for supporting informational content that should be visually separated from the surrounding page. */
   "prop:info"?: WarpBox["info"];
-  /**  */
+  /** Shows the box with neutral styling.
+Use this for quiet grouped content that needs a background without strong emphasis. */
   "prop:neutral"?: WarpBox["neutral"];
-  /**  */
+  /** ARIA role for the box wrapper.
+Defaults to a role of `region`. Set `role="none"` to override this behaviour for purely visual grouping, or set a specific role when the box has a clearer semantic purpose. */
   "prop:role"?: WarpBox["role"];
 
   /** Set the innerHTML of the element */
@@ -2156,11 +2166,16 @@ export type CustomElements = {
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
-   * - `bleed`: undefined
-   * - `bordered`: undefined
-   * - `info`: undefined
-   * - `neutral`: undefined
-   * - `role`: undefined
+   * - `bleed`: Makes the box bleed to the container edge.
+   * Extends the box into the horizontal gutter on narrow screens. Adds negative horizontal margins and square side corners below the small breakpoint, then restores the normal margins and rounded corners from the small breakpoint and up.
+   * - `bordered`: Shows the box as a bordered surface.
+   * Use this when the content needs a clear visual boundary from the surrounding page.
+   * - `info`: Shows the box with information styling.
+   * Use this for supporting informational content that should be visually separated from the surrounding page.
+   * - `neutral`: Shows the box with neutral styling.
+   * Use this for quiet grouped content that needs a background without strong emphasis.
+   * - `role`: ARIA role for the box wrapper.
+   * Defaults to a role of `region`. Set `role="none"` to override this behaviour for purely visual grouping, or set a specific role when the box has a clearer semantic purpose.
    */
   "w-box": Partial<WarpBoxProps & BaseProps<WarpBox> & BaseEvents>;
 
@@ -3194,11 +3209,16 @@ export type CustomElementsSolidJs = {
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
-   * - `bleed`: undefined
-   * - `bordered`: undefined
-   * - `info`: undefined
-   * - `neutral`: undefined
-   * - `role`: undefined
+   * - `bleed`: Makes the box bleed to the container edge.
+   * Extends the box into the horizontal gutter on narrow screens. Adds negative horizontal margins and square side corners below the small breakpoint, then restores the normal margins and rounded corners from the small breakpoint and up.
+   * - `bordered`: Shows the box as a bordered surface.
+   * Use this when the content needs a clear visual boundary from the surrounding page.
+   * - `info`: Shows the box with information styling.
+   * Use this for supporting informational content that should be visually separated from the surrounding page.
+   * - `neutral`: Shows the box with neutral styling.
+   * Use this for quiet grouped content that needs a background without strong emphasis.
+   * - `role`: ARIA role for the box wrapper.
+   * Defaults to a role of `region`. Set `role="none"` to override this behaviour for purely visual grouping, or set a specific role when the box has a clearer semantic purpose.
    */
   "w-box": Partial<
     WarpBoxProps & WarpBoxSolidJsProps & BaseProps<WarpBox> & BaseEvents