@orange-halo/components 2.1.0 → 3.0.0

package/dist/oh-checkbox.js

@@ -1,28 +1,23 @@
 /**
  * oh-checkbox
  *
- * A chunky, playful checkbox with hand-crafted feel.
- * Matches the inset/pressed aesthetic of oh-input.
- *
  * DESIGN DECISIONS:
  * ─────────────────
- * 1. CHUNKY & TACTILE
- *    - Thick border (stroke.control)
- *    - Inset shadow when unchecked (pressed into page)
- *    - shape.compact corners (smaller than buttons)
+ * 1. LOOK FROM TOKENS
+ *    - Border: stroke.control in color.border.emphasis
+ *    - Corners: shape.compact (smaller than the other controls' shape.control)
+ *    - Shadow: offset by elevation.offset.* in elevation.color.secondary; hover and
+ *      press move the box by lift.hoverSm / lift.pressSm
  *
  * 2. CHECKED STATE
- *    - Filled with primary color
- *    - Custom chunky checkmark
- *    - Shadow shifts to feel "activated"
+ *    - Filled with color.brand.primary, a checkmark in color.text.onBrand,
+ *      and the shadow in elevation.color.primary
  *
  * 3. ACCESSIBILITY
- *    - Native checkbox hidden but accessible
+ *    - A native checkbox, visually hidden but focusable and announced; the
+ *      drawn box is decoration
  *    - Label always required
- *    - Focus ring matches input (even inner ring)
- *    - Minimum touch target 44px
- *
- * @element oh-checkbox
+ *    - Focus underlines the label (a solid indicator)
  */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -33,6 +28,44 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { html, css, nothing } from "lit";
 import { customElement, property, state } from "lit/decorators.js";
 import { OhElement, baseStyles } from "./base.js";
+/**
+ * A single checkbox with its label, for turning one option on or off.
+ *
+ * **Use it for** one yes/no choice, such as agreeing to terms, or as part of
+ * a set where any number can be chosen. **Don't use it for** a set of
+ * related options on its own (use `oh-checkbox-group`, which adds the
+ * fieldset and legend), one choice from several (use `oh-radio-group`), or a
+ * setting that applies straight away (use `oh-toggle`).
+ *
+ * **States:** unchecked, checked, hover, active, focus, error (set `error-text`).
+ *
+ * **Behaviour:** clicking the box or the label toggles it, as does Space
+ * when it's focused. Each change sets `checked` and fires `oh-change`. The
+ * native `<input type="checkbox">` sits in the shadow root, so it doesn't
+ * submit with a native form: read `checked` or listen for `oh-change`. It
+ * has no `disabled` property.
+ *
+ * **Accessibility:** a real native checkbox, visually hidden, carries the
+ * role, state and keyboard behaviour; the drawn box is decoration. Always
+ * set `label`: it's the checkbox's name. Focus underlines the label. The
+ * error message shows under the checkbox with an icon, sets `aria-invalid`
+ * and is linked with `aria-describedby`; it's announced (`role="alert"`)
+ * only when it appears after first render.
+ *
+ * **Look:** set by tokens — `stroke.control` in `color.border.emphasis`
+ * (border), `shape.compact` (corners), `typography.control.*` (label),
+ * `elevation.offset.*` and `elevation.color.secondary` (shadow), `lift.hoverSm` /
+ * `lift.pressSm` (movement on hover and press), `color.border.hover`
+ * (hover), `color.brand.primary` (and its hover and active tokens),
+ * `color.text.onBrand` and `elevation.color.primary` (checked),
+ * `color.feedback.error` and `elevation.color.error` (error).
+ *
+ * @element oh-checkbox
+ * @fires oh-change - The checkbox was toggled. detail: { checked, value }
+ * @csspart box - The drawn checkbox
+ * @csspart label - The label text
+ * @csspart error - The error message
+ */
 let OhCheckbox = class OhCheckbox extends OhElement {
     constructor() {
         super(...arguments);
@@ -40,8 +73,11 @@ let OhCheckbox = class OhCheckbox extends OhElement {
         this.label = "";
         this.name = "";
         this.value = "";
-        this.error = false;
-        this.errorMessage = "";
+        /**
+         * Error shown with the control and linked to it. Setting it puts the
+         * control in its error state; clear it to leave that state.
+         */
+        this.errorText = "";
         /**
          * Force a visual state (for documentation/Figma sync only)
          * Values: 'hover' | 'focus'
@@ -58,11 +94,6 @@ let OhCheckbox = class OhCheckbox extends OhElement {
     static { this.styles = [
         baseStyles,
         css `
-      /* ═══════════════════════════════════════════════════════════════
-         ORANGE HALO CHECKBOX
-         Chunky • Tactile • Playful
-         ═══════════════════════════════════════════════════════════════ */
-
       :host {
         display: inline-block;
       }
@@ -96,25 +127,26 @@ let OhCheckbox = class OhCheckbox extends OhElement {
         width: 24px;
         height: 24px;
         flex-shrink: 0;
-        
-        /* Chunky border */
+
+        /* Border: stroke.control in color.border.emphasis */
         border: var(--oh-stroke-control) solid var(--oh-color-border-emphasis);
         border-radius: var(--oh-shape-compact);
-        
-        /* Offset shadow like primary button */
+
+        /* Offset shadow: elevation.offset.md in elevation.color.secondary */
         background-color: var(--oh-color-surface-base);
-        box-shadow: var(--oh-elevation-offset-md) var(--oh-elevation-offset-md) 0 0 var(--oh-shadow-secondary);
-        
-        transition: 
-          transform var(--oh-motion-snappy) var(--oh-motion-ease-playful),
-          box-shadow var(--oh-motion-snappy) var(--oh-motion-ease-playful),
+        box-shadow: var(--oh-elevation-offset-md) var(--oh-elevation-offset-md)
+          0 0 var(--oh-elevation-color-secondary);
+
+        transition:
+          transform var(--oh-motion-snappy) var(--oh-motion-ease-emphasized),
+          box-shadow var(--oh-motion-snappy) var(--oh-motion-ease-emphasized),
           background-color var(--oh-motion-quick) ease,
           border-color var(--oh-motion-quick) ease;
       }
 
       /* Checkmark (hidden by default) */
       .checkbox-box::after {
-        content: '';
+        content: "";
         position: absolute;
         top: 3px;
         left: 7px;
@@ -131,24 +163,27 @@ let OhCheckbox = class OhCheckbox extends OhElement {
          STATES
          ═══════════════════════════════════════════════════════════════ */
 
-      /* Hover: lift up-left, shadow grows */
+      /* Hover: moves by lift.hoverSm; shadow offset elevation.offset.lg */
       .checkbox-wrapper:hover .checkbox-box {
         border-color: var(--oh-color-border-hover);
         transform: translate(var(--oh-lift-hover-sm), var(--oh-lift-hover-sm));
-        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg) 0 0 var(--oh-shadow-secondary);
+        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg)
+          0 0 var(--oh-elevation-color-secondary);
       }
 
-      /* Active: press down-right, shadow shrinks */
+      /* Active: moves by lift.pressSm; shadow offset elevation.offset.xs */
       .checkbox-wrapper:active .checkbox-box {
         transform: translate(var(--oh-lift-press-sm), var(--oh-lift-press-sm));
-        box-shadow: var(--oh-elevation-offset-xs) var(--oh-elevation-offset-xs) 0 0 var(--oh-shadow-secondary);
+        box-shadow: var(--oh-elevation-offset-xs) var(--oh-elevation-offset-xs)
+          0 0 var(--oh-elevation-color-secondary);
       }
 
-      /* Checked: primary color with warm shadow */
+      /* Checked: color.brand.primary fill, elevation.color.primary shadow */
       .native-checkbox:checked + .checkbox-box {
         background-color: var(--oh-color-brand-primary);
         border-color: var(--oh-color-brand-primary);
-        box-shadow: var(--oh-elevation-offset-md) var(--oh-elevation-offset-md) 0 0 var(--oh-shadow-primary);
+        box-shadow: var(--oh-elevation-offset-md) var(--oh-elevation-offset-md)
+          0 0 var(--oh-elevation-color-primary);
       }
 
       .native-checkbox:checked + .checkbox-box::after {
@@ -160,14 +195,16 @@ let OhCheckbox = class OhCheckbox extends OhElement {
         background-color: var(--oh-color-brand-primary-hover);
         border-color: var(--oh-color-brand-primary-hover);
         transform: translate(var(--oh-lift-hover-sm), var(--oh-lift-hover-sm));
-        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg) 0 0 var(--oh-shadow-primary);
+        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg)
+          0 0 var(--oh-elevation-color-primary);
       }
 
       /* Checked + Active */
       .checkbox-wrapper:active .native-checkbox:checked + .checkbox-box {
         background-color: var(--oh-color-brand-primary-active);
         transform: translate(var(--oh-lift-press-sm), var(--oh-lift-press-sm));
-        box-shadow: var(--oh-elevation-offset-xs) var(--oh-elevation-offset-xs) 0 0 var(--oh-shadow-primary);
+        box-shadow: var(--oh-elevation-offset-xs) var(--oh-elevation-offset-xs)
+          0 0 var(--oh-elevation-color-primary);
       }
 
       /* Focus: underline the label (accessible indicator) */
@@ -193,14 +230,16 @@ let OhCheckbox = class OhCheckbox extends OhElement {
          ERROR STATE
          ═══════════════════════════════════════════════════════════════ */
 
-      :host([error]) .checkbox-box {
+      :host([data-invalid]) .checkbox-box {
         border-color: var(--oh-color-feedback-error);
-        box-shadow: var(--oh-elevation-offset-md) var(--oh-elevation-offset-md) 0 0 var(--oh-shadow-error);
+        box-shadow: var(--oh-elevation-offset-md) var(--oh-elevation-offset-md)
+          0 0 var(--oh-elevation-color-error);
       }
 
-      :host([error]) .checkbox-wrapper:hover .checkbox-box {
+      :host([data-invalid]) .checkbox-wrapper:hover .checkbox-box {
         border-color: var(--oh-color-feedback-error-hover);
-        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg) 0 0 var(--oh-shadow-error);
+        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg)
+          0 0 var(--oh-elevation-color-error);
       }
 
       .error-message {
@@ -239,7 +278,8 @@ let OhCheckbox = class OhCheckbox extends OhElement {
       :host([force-state="hover"]) .checkbox-box {
         border-color: var(--oh-color-border-hover);
         transform: translate(var(--oh-lift-hover-sm), var(--oh-lift-hover-sm));
-        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg) 0 0 var(--oh-shadow-secondary);
+        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg)
+          0 0 var(--oh-elevation-color-secondary);
       }
 
       /* Forced Focus - Unchecked */
@@ -253,7 +293,8 @@ let OhCheckbox = class OhCheckbox extends OhElement {
         background-color: var(--oh-color-brand-primary-hover);
         border-color: var(--oh-color-brand-primary-hover);
         transform: translate(var(--oh-lift-hover-sm), var(--oh-lift-hover-sm));
-        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg) 0 0 var(--oh-shadow-primary);
+        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg)
+          0 0 var(--oh-elevation-color-primary);
       }
     `,
     ]; }
@@ -262,9 +303,14 @@ let OhCheckbox = class OhCheckbox extends OhElement {
         this.checked = target.checked;
         this.emit("oh-change", { checked: this.checked, value: this.value });
     }
+    updated(changed) {
+        // Styling hook for the error state (data-invalid on the host)
+        if (changed.has("errorText"))
+            this.toggleAttribute("data-invalid", !!this.errorText);
+    }
     willUpdate(changed) {
-        if (this.hasUpdated && (changed.has("error") || changed.has("errorMessage"))) {
-            this._announceError = !!(this.error && this.errorMessage);
+        if (this.hasUpdated && changed.has("errorText")) {
+            this._announceError = !!this.errorText;
         }
     }
     render() {
@@ -279,20 +325,34 @@ let OhCheckbox = class OhCheckbox extends OhElement {
             name=${this.name}
             .value=${this.value}
             .checked=${this.checked}
-            aria-invalid=${this.error ? "true" : "false"}
-            aria-describedby=${this.error && this.errorMessage ? this._errorId : nothing}
+            aria-invalid=${this.errorText ? "true" : "false"}
+            aria-describedby=${this.errorText ? this._errorId : nothing}
             @change=${this._handleChange}
           />
           <span class="checkbox-box" part="box"></span>
           <span class="label" part="label">${this.label}</span>
         </label>
-        ${this.error && this.errorMessage
+        ${this.errorText
             ? html `
-              <div id=${this._errorId} class="error-message" part="error" role=${this._announceError ? "alert" : nothing}>
-                <svg class="error-icon" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
-                  <path fill-rule="evenodd" d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-8-5a.75.75 0 01.75.75v4.5a.75.75 0 01-1.5 0v-4.5A.75.75 0 0110 5zm0 10a1 1 0 100-2 1 1 0 000 2z" clip-rule="evenodd" />
+              <div
+                id=${this._errorId}
+                class="error-message"
+                part="error"
+                role=${this._announceError ? "alert" : nothing}
+              >
+                <svg
+                  class="error-icon"
+                  viewBox="0 0 20 20"
+                  fill="currentColor"
+                  aria-hidden="true"
+                >
+                  <path
+                    fill-rule="evenodd"
+                    d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-8-5a.75.75 0 01.75.75v4.5a.75.75 0 01-1.5 0v-4.5A.75.75 0 0110 5zm0 10a1 1 0 100-2 1 1 0 000 2z"
+                    clip-rule="evenodd"
+                  />
                 </svg>
-                ${this.errorMessage}
+                ${this.errorText}
               </div>
             `
             : ""}
@@ -313,11 +373,8 @@ __decorate([
     property({ type: String })
 ], OhCheckbox.prototype, "value", void 0);
 __decorate([
-    property({ type: Boolean, reflect: true })
-], OhCheckbox.prototype, "error", void 0);
-__decorate([
-    property({ type: String })
-], OhCheckbox.prototype, "errorMessage", void 0);
+    property({ type: String, attribute: "error-text" })
+], OhCheckbox.prototype, "errorText", void 0);
 __decorate([
     property({ type: String, reflect: true, attribute: "force-state" })
 ], OhCheckbox.prototype, "forceState", void 0);

package/dist/oh-checkbox.js.map

@@ -1 +1 @@
-{"version":3,"file":"oh-checkbox.js","sourceRoot":"","sources":["../src/oh-checkbox.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"oh-checkbox.js","sourceRoot":"","sources":["../src/oh-checkbox.ts"],"names":[],"mappings":"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"}

package/dist/oh-cluster.d.ts

@@ -1,27 +1,32 @@
 /**
  * oh-cluster
  *
- * Horizontal grouping with wrap and gap.
- * Perfect for button groups, tags, navigation items.
- *
  * DESIGN DECISIONS:
  * ─────────────────
- * 1. FLEX WRAP BY DEFAULT
- *    - Items wrap to next line when needed
- *    - Consistent gaps in both directions
- *
- * 2. JUSTIFY OPTIONS
- *    - start, center, end, between, around
- *
- * 3. ALIGNMENT OPTIONS
- *    - start, center, end, baseline
- *
- * @element oh-cluster
+ * 1. A wrapping flex row (unless `nowrap`); `gap` maps named steps to
+ *    `spacing.*` tokens, the same in both directions.
+ * 2. Justify: start, center, end, between, around.
+ * 3. Align: start, center (default), end, baseline.
  */
 import { OhElement } from "./base.js";
 export type ClusterGap = "none" | "xs" | "sm" | "md" | "lg" | "xl";
 export type ClusterJustify = "start" | "center" | "end" | "between" | "around";
 export type ClusterAlign = "start" | "center" | "end" | "baseline";
+/**
+ * A horizontal group of items that wraps onto new lines when space runs out.
+ *
+ * **Use it for** button groups, tags and rows of links. **Don't use it for**
+ * vertical lists (use `oh-stack`) or equal-width columns (use `oh-grid`).
+ *
+ * **Gaps:** `gap` is `none`, `xs` (`spacing.1`), `sm` (`spacing.2`), `md`
+ * (default, `spacing.4`), `lg` (`spacing.6`) or `xl` (`spacing.8`), between
+ * items and between rows. `justify` is `start` (default), `center`, `end`,
+ * `between` or `around`; `align` is `start`, `center` (default), `end` or
+ * `baseline`. `nowrap` keeps everything on one line.
+ *
+ * @element oh-cluster
+ * @slot - The items to group.
+ */
 export declare class OhCluster extends OhElement {
     static styles: import("lit").CSSResult[];
     gap: ClusterGap;

package/dist/oh-cluster.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oh-cluster.d.ts","sourceRoot":"","sources":["../src/oh-cluster.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,EAAE,SAAS,EAAc,MAAM,WAAW,CAAC;AAElD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AACnE,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,GAAG,QAAQ,CAAC;AAC/E,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,UAAU,CAAC;AAEnE,qBACa,SAAU,SAAQ,SAAS;IACtC,OAAgB,MAAM,4BAkFpB;IAGF,GAAG,EAAE,UAAU,CAAQ;IAGvB,OAAO,EAAE,cAAc,CAAW;IAGlC,KAAK,EAAE,YAAY,CAAY;IAG/B,MAAM,UAAS;IAEf,MAAM;CAGP;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,YAAY,EAAE,SAAS,CAAC;KACzB;CACF"}
+{"version":3,"file":"oh-cluster.d.ts","sourceRoot":"","sources":["../src/oh-cluster.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,SAAS,EAAc,MAAM,WAAW,CAAC;AAElD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AACnE,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,GAAG,QAAQ,CAAC;AAC/E,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,UAAU,CAAC;AAEnE;;;;;;;;;;;;;;GAcG;AACH,qBACa,SAAU,SAAQ,SAAS;IACtC,OAAgB,MAAM,4BA6EpB;IAGF,GAAG,EAAE,UAAU,CAAQ;IAGvB,OAAO,EAAE,cAAc,CAAW;IAGlC,KAAK,EAAE,YAAY,CAAY;IAG/B,MAAM,UAAS;IAEf,MAAM;CAGP;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,YAAY,EAAE,SAAS,CAAC;KACzB;CACF"}

package/dist/oh-cluster.js

@@ -1,22 +1,12 @@
 /**
  * oh-cluster
  *
- * Horizontal grouping with wrap and gap.
- * Perfect for button groups, tags, navigation items.
- *
  * DESIGN DECISIONS:
  * ─────────────────
- * 1. FLEX WRAP BY DEFAULT
- *    - Items wrap to next line when needed
- *    - Consistent gaps in both directions
- *
- * 2. JUSTIFY OPTIONS
- *    - start, center, end, between, around
- *
- * 3. ALIGNMENT OPTIONS
- *    - start, center, end, baseline
- *
- * @element oh-cluster
+ * 1. A wrapping flex row (unless `nowrap`); `gap` maps named steps to
+ *    `spacing.*` tokens, the same in both directions.
+ * 2. Justify: start, center, end, between, around.
+ * 3. Align: start, center (default), end, baseline.
  */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -27,6 +17,21 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { html, css } from "lit";
 import { customElement, property } from "lit/decorators.js";
 import { OhElement, baseStyles } from "./base.js";
+/**
+ * A horizontal group of items that wraps onto new lines when space runs out.
+ *
+ * **Use it for** button groups, tags and rows of links. **Don't use it for**
+ * vertical lists (use `oh-stack`) or equal-width columns (use `oh-grid`).
+ *
+ * **Gaps:** `gap` is `none`, `xs` (`spacing.1`), `sm` (`spacing.2`), `md`
+ * (default, `spacing.4`), `lg` (`spacing.6`) or `xl` (`spacing.8`), between
+ * items and between rows. `justify` is `start` (default), `center`, `end`,
+ * `between` or `around`; `align` is `start`, `center` (default), `end` or
+ * `baseline`. `nowrap` keeps everything on one line.
+ *
+ * @element oh-cluster
+ * @slot - The items to group.
+ */
 let OhCluster = class OhCluster extends OhElement {
     constructor() {
         super(...arguments);
@@ -38,11 +43,6 @@ let OhCluster = class OhCluster extends OhElement {
     static { this.styles = [
         baseStyles,
         css `
-      /* ═══════════════════════════════════════════════════════════════
-         ORANGE HALO CLUSTER
-         Horizontal grouping • Flex wrap • Consistent gaps
-         ═══════════════════════════════════════════════════════════════ */
-
       :host {
         display: flex;
         flex-wrap: wrap;

package/dist/oh-cluster.js.map

@@ -1 +1 @@
-{"version":3,"file":"oh-cluster.js","sourceRoot":"","sources":["../src/oh-cluster.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;;;;;;AAEH,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAO3C,IAAM,SAAS,GAAf,MAAM,SAAU,SAAQ,SAAS;IAAjC;;QAsFL,QAAG,GAAe,IAAI,CAAC;QAGvB,YAAO,GAAmB,OAAO,CAAC;QAGlC,UAAK,GAAiB,QAAQ,CAAC;QAG/B,WAAM,GAAG,KAAK,CAAC;IAKjB,CAAC;aAnGiB,WAAM,GAAG;QACvB,UAAU;QACV,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA+EF;KACF,AAlFqB,CAkFpB;IAcF,MAAM;QACJ,OAAO,IAAI,CAAA,eAAe,CAAC;IAC7B,CAAC;;AAbD;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;sCACnB;AAGvB;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;0CACR;AAGlC;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;wCACX;AAG/B;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;yCAC5B;AA/FJ,SAAS;IADrB,aAAa,CAAC,YAAY,CAAC;GACf,SAAS,CAoGrB"}
+{"version":3,"file":"oh-cluster.js","sourceRoot":"","sources":["../src/oh-cluster.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;;;;;;;AAEH,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAMlD;;;;;;;;;;;;;;GAcG;AAEI,IAAM,SAAS,GAAf,MAAM,SAAU,SAAQ,SAAS;IAAjC;;QAiFL,QAAG,GAAe,IAAI,CAAC;QAGvB,YAAO,GAAmB,OAAO,CAAC;QAGlC,UAAK,GAAiB,QAAQ,CAAC;QAG/B,WAAM,GAAG,KAAK,CAAC;IAKjB,CAAC;aA9FiB,WAAM,GAAG;QACvB,UAAU;QACV,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA0EF;KACF,AA7EqB,CA6EpB;IAcF,MAAM;QACJ,OAAO,IAAI,CAAA,eAAe,CAAC;IAC7B,CAAC;;AAbD;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;sCACnB;AAGvB;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;0CACR;AAGlC;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;wCACX;AAG/B;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;yCAC5B;AA1FJ,SAAS;IADrB,aAAa,CAAC,YAAY,CAAC;GACf,SAAS,CA+FrB"}

package/dist/oh-container.d.ts

@@ -1,29 +1,32 @@
 /**
  * oh-container
  *
- * Max-width wrapper with centered content.
- * Used to constrain content width and provide consistent horizontal padding.
- *
  * DESIGN DECISIONS:
  * ─────────────────
- * 1. RESPONSIVE MAX-WIDTHS (layout.container.*)
- *    - sm: tight, focused content
- *    - md: articles, forms
- *    - lg: standard pages
- *    - xl: wide layouts
- *    - full: 100% (edge-to-edge)
+ * 1. Max-widths come only from `layout.container.*` (sm, md, lg, xl);
+ *    `full` is edge to edge with no padding.
+ * 2. Horizontal padding from `spacing.*`, stepping up at the
+ *    `size.breakpoint.sm` and `size.breakpoint.lg` widths.
+ * 3. Centred with auto margins.
+ */
+import { OhElement } from "./base.js";
+export type ContainerSize = "sm" | "md" | "lg" | "xl" | "full";
+/**
+ * A centred wrapper that limits content to a maximum width and adds side padding.
+ *
+ * **Use it for** the outer width of a page or section. **Don't use it for**
+ * spacing between items (use `oh-stack`, `oh-cluster` or `oh-grid`).
  *
- * 2. CONSISTENT PADDING
- *    - Uses spacing tokens for horizontal padding
- *    - Responsive padding on smaller screens
+ * **Sizes:** `size` picks the max-width: `sm`, `md`, `lg` (default) and `xl`
+ * use `layout.container.sm` to `layout.container.xl`; `full` is the full
+ * width with no side padding. `center` centres the text.
  *
- * 3. CENTERED BY DEFAULT
- *    - margin: 0 auto for horizontal centering
+ * **Behaviour:** side padding is `spacing.4`, rising to `spacing.6` from the
+ * `size.breakpoint.sm` width and `spacing.8` from `size.breakpoint.lg`.
  *
  * @element oh-container
+ * @slot - The content to contain.
  */
-import { OhElement } from "./base.js";
-export type ContainerSize = "sm" | "md" | "lg" | "xl" | "full";
 export declare class OhContainer extends OhElement {
     static styles: import("lit").CSSResult[];
     size: ContainerSize;

package/dist/oh-container.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oh-container.d.ts","sourceRoot":"","sources":["../src/oh-container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,EAAE,SAAS,EAAc,MAAM,WAAW,CAAC;AAElD,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC;AAE/D,qBACa,WAAY,SAAQ,SAAS;IACxC,OAAgB,MAAM,4BA6DpB;IAGF,IAAI,EAAE,aAAa,CAAQ;IAG3B,MAAM,UAAS;IAEf,MAAM;CAGP;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,cAAc,EAAE,WAAW,CAAC;KAC7B;CACF"}
+{"version":3,"file":"oh-container.d.ts","sourceRoot":"","sources":["../src/oh-container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAE,SAAS,EAAc,MAAM,WAAW,CAAC;AAElD,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC;AAE/D;;;;;;;;;;;;;;;GAeG;AACH,qBACa,WAAY,SAAQ,SAAS;IACxC,OAAgB,MAAM,4BAwDpB;IAGF,IAAI,EAAE,aAAa,CAAQ;IAG3B,MAAM,UAAS;IAEf,MAAM;CAGP;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,cAAc,EAAE,WAAW,CAAC;KAC7B;CACF"}

package/dist/oh-container.js

@@ -1,26 +1,13 @@
 /**
  * oh-container
  *
- * Max-width wrapper with centered content.
- * Used to constrain content width and provide consistent horizontal padding.
- *
  * DESIGN DECISIONS:
  * ─────────────────
- * 1. RESPONSIVE MAX-WIDTHS (layout.container.*)
- *    - sm: tight, focused content
- *    - md: articles, forms
- *    - lg: standard pages
- *    - xl: wide layouts
- *    - full: 100% (edge-to-edge)
- *
- * 2. CONSISTENT PADDING
- *    - Uses spacing tokens for horizontal padding
- *    - Responsive padding on smaller screens
- *
- * 3. CENTERED BY DEFAULT
- *    - margin: 0 auto for horizontal centering
- *
- * @element oh-container
+ * 1. Max-widths come only from `layout.container.*` (sm, md, lg, xl);
+ *    `full` is edge to edge with no padding.
+ * 2. Horizontal padding from `spacing.*`, stepping up at the
+ *    `size.breakpoint.sm` and `size.breakpoint.lg` widths.
+ * 3. Centred with auto margins.
  */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -31,6 +18,22 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { html, css } from "lit";
 import { customElement, property } from "lit/decorators.js";
 import { OhElement, baseStyles } from "./base.js";
+/**
+ * A centred wrapper that limits content to a maximum width and adds side padding.
+ *
+ * **Use it for** the outer width of a page or section. **Don't use it for**
+ * spacing between items (use `oh-stack`, `oh-cluster` or `oh-grid`).
+ *
+ * **Sizes:** `size` picks the max-width: `sm`, `md`, `lg` (default) and `xl`
+ * use `layout.container.sm` to `layout.container.xl`; `full` is the full
+ * width with no side padding. `center` centres the text.
+ *
+ * **Behaviour:** side padding is `spacing.4`, rising to `spacing.6` from the
+ * `size.breakpoint.sm` width and `spacing.8` from `size.breakpoint.lg`.
+ *
+ * @element oh-container
+ * @slot - The content to contain.
+ */
 let OhContainer = class OhContainer extends OhElement {
     constructor() {
         super(...arguments);
@@ -40,11 +43,6 @@ let OhContainer = class OhContainer extends OhElement {
     static { this.styles = [
         baseStyles,
         css `
-      /* ═══════════════════════════════════════════════════════════════
-         ORANGE HALO CONTAINER
-         Max-width wrapper • Centered content • Responsive padding
-         ═══════════════════════════════════════════════════════════════ */
-
       :host {
         display: block;
         width: 100%;

package/dist/oh-container.js.map

@@ -1 +1 @@
-{"version":3,"file":"oh-container.js","sourceRoot":"","sources":["../src/oh-container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;;;;;;;AAEH,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAK3C,IAAM,WAAW,GAAjB,MAAM,WAAY,SAAQ,SAAS;IAAnC;;QAiEL,SAAI,GAAkB,IAAI,CAAC;QAG3B,WAAM,GAAG,KAAK,CAAC;IAKjB,CAAC;aAxEiB,WAAM,GAAG;QACvB,UAAU;QACV,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA0DF;KACF,AA7DqB,CA6DpB;IAQF,MAAM;QACJ,OAAO,IAAI,CAAA,eAAe,CAAC;IAC7B,CAAC;;AAPD;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;yCACf;AAG3B;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;2CAC5B;AApEJ,WAAW;IADvB,aAAa,CAAC,cAAc,CAAC;GACjB,WAAW,CAyEvB"}
+{"version":3,"file":"oh-container.js","sourceRoot":"","sources":["../src/oh-container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;;;;;;;AAEH,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAIlD;;;;;;;;;;;;;;;GAeG;AAEI,IAAM,WAAW,GAAjB,MAAM,WAAY,SAAQ,SAAS;IAAnC;;QA4DL,SAAI,GAAkB,IAAI,CAAC;QAG3B,WAAM,GAAG,KAAK,CAAC;IAKjB,CAAC;aAnEiB,WAAM,GAAG;QACvB,UAAU;QACV,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAqDF;KACF,AAxDqB,CAwDpB;IAQF,MAAM;QACJ,OAAO,IAAI,CAAA,eAAe,CAAC;IAC7B,CAAC;;AAPD;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;yCACf;AAG3B;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;2CAC5B;AA/DJ,WAAW;IADvB,aAAa,CAAC,cAAc,CAAC;GACjB,WAAW,CAoEvB"}

package/dist/oh-drawer.d.ts

@@ -7,31 +7,48 @@
  * ─────────────────
  * 1. POSITIONING
  *    - Slides in from left or right
- *    - Full height, configurable width
- *    - Overlays content with warm backdrop
+ *    - Full height, width set by --oh-drawer-width
+ *    - Overlays content with a color.surface.overlay backdrop
  *
- * 2. STYLING
- *    - Chunky border on the edge
- *    - Warm surface background
- *    - Smooth slide animation
+ * 2. LOOK FROM TOKENS
+ *    - Panel: color.surface.base
+ *    - Shadow: elevation.strong (left); an elevation.offset.lg offset in
+ *      color.border.strong (right)
+ *    - Slide: motion.relaxed with motion.easeGentle, off under reduced motion
  *
  * 3. ACCESSIBILITY
  *    - Focus trap when open (focus guards at each end of the panel)
  *    - Escape key closes
  *    - aria-modal and role="dialog"
  *    - Returns focus to trigger on close
+ *    - inert while closed, and hidden once it has slid away
+ */
+import { OhElement } from "./base.js";
+import "./oh-button.js";
+import "./oh-icon.js";
+/**
+ * A panel that slides in from the side of the viewport, over the page, for navigation or supplementary content.
+ *
+ * **Use it for** a site's navigation on small screens, filters, or settings that relate to the page behind. **Don't use it for** a decision the user must make before going on (use `oh-modal`); or for content that should always be visible (put it in the page).
+ *
+ * **Parts:** `heading` (an optional visible `h2`), a built-in Close button, and the default slot for the content, which scrolls when it's taller than the viewport.
+ *
+ * **Positions:** `left` (default) or `right`.
+ *
+ * **Behaviour:** set `open`, or call `show()` and `hide()`. On open, focus moves to the Close button, Tab and Shift+Tab wrap inside the panel, and the page behind stops scrolling. The Close button, Escape, a click on the backdrop and `hide()` close it and fire `oh-close`; focus then returns to the element that opened it. While closed the panel is `inert`. Motion is off under `prefers-reduced-motion`.
+ *
+ * **Accessibility:** the panel is `role="dialog"` with `aria-modal="true"`, labelled by `heading`, or "Navigation menu" when there's no heading, so set `heading` for any other use. The Close button's accessible name is "Close menu".
+ *
+ * **Look:** set by tokens. `color.surface.overlay` sets the backdrop and `color.surface.base` the panel. A left drawer's shadow is `elevation.strong`; a right drawer's is an `elevation.offset.lg` offset in `color.border.strong`. The heading uses `typography.heading.h5.fontSize` and `typography.emphasis.fontWeight`. Motion uses `motion.relaxed` and `motion.easeGentle`. `--oh-drawer-width` sets the width.
  *
  * @element oh-drawer
  *
  * @slot - Default slot for drawer content
  *
- * @fires oh-close - When the drawer is closed
+ * @fires oh-close - When the drawer is closed by the Close button, Escape, the backdrop or `hide()`. Not fired when you set `open` to false yourself.
  *
- * @cssprop --oh-drawer-width - Width of the drawer (default: 280px)
+ * @cssprop --oh-drawer-width - Width of the drawer. It never fills the whole viewport width.
  */
-import { OhElement } from "./base.js";
-import "./oh-button.js";
-import "./oh-icon.js";
 export declare class OhDrawer extends OhElement {
     static styles: import("lit").CSSResult[];
     /** Whether the drawer is open */