@orange-halo/components 2.2.0 → 3.1.0

package/dist/oh-button.js

@@ -1,32 +1,23 @@
 /**
  * oh-button
  *
- * A chunky, confident button with playful personality.
- * Inspired by hand-crafted, illustrative UI — not corporate SaaS.
- *
  * DESIGN DECISIONS:
  * ─────────────────
- * 1. CHUNKY & CONFIDENT
- *    - Thick border (stroke.control) that feels illustrative
- *    - Solid fills, no subtle gradients
- *    - Generous padding, substantial presence
- *
- * 2. OFFSET SHADOW (STICKER EFFECT)
- *    - Shadow offset to bottom-right
- *    - Feels like a physical sticker or stamp
- *    - Not a generic centered drop shadow
- *
- * 3. PLAYFUL INTERACTIONS
- *    - Hover: slight upward lift + shadow grows
- *    - Active: pressed down, shadow shrinks (stamp effect)
- *    - Focus: warm glow + accessible underline
- *
- * 4. HAND-CRAFTED FEEL
- *    - Bold, defined edges
- *    - Confident color choices
- *    - Personality over polish
- *
- * @element oh-button
+ * 1. Renders a native <button>, or an <a> when `href` is set, inside the
+ *    shadow root, so keyboard and screen reader behaviour come from the
+ *    platform. `accessible-label` is forwarded to it (an aria-label on the
+ *    host isn't).
+ * 2. Look comes from button.* component tokens: button.base.borderWidth
+ *    (stroke.control), button.base.borderRadius (shape.control),
+ *    button.variant.<variant>.* for fills, text, border and shadow colour,
+ *    button.size.<size>.* for type, padding and height.
+ * 3. Hover and active move the button by lift.hoverMd / lift.pressMd and set
+ *    the shadow offset to elevation.offset.2xl / elevation.offset.xs (rest is
+ *    elevation.offset.lg).
+ * 4. Focus is a solid underline on the label (an underline the button draws
+ *    itself for icon-only and loading buttons, whose text is hidden).
+ * 5. Loading uses aria-disabled + aria-busy, not disabled, so focus stays on
+ *    the button.
  */
 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;
@@ -37,6 +28,41 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { html, css, nothing } from "lit";
 import { customElement, property } from "lit/decorators.js";
 import { OhElement, baseStyles } from "./base.js";
+/**
+ * A button that starts an action, or a link styled as a button when `href` is set.
+ *
+ * **Use it for** actions: submitting, saving, opening a dialog, confirming.
+ * **Don't use it for** links inside running text (use `oh-link`).
+ *
+ * **Variants:** `primary` for the main action, `secondary` for the others,
+ * `accent` for an action that takes the accent colour role. **Sizes:** `sm`, `md` (default), `lg`.
+ * **States:** rest, hover, active, focus and `loading`.
+ *
+ * **Behaviour:** fires `oh-click` when the inner `<button>` is clicked, except
+ * while `loading`. `loading` shows a spinner, keeps the label for screen
+ * readers, sets `aria-busy` and `aria-disabled` and ignores clicks, while the
+ * button stays focusable. With `href` it renders an `<a>` (and
+ * `target="_blank"` adds `rel="noopener noreferrer"`); link buttons don't fire
+ * `oh-click`. It has no `disabled` property and doesn't submit a form by
+ * itself: handle `oh-click`. Under `prefers-reduced-motion` it doesn't move.
+ *
+ * **Accessibility:** focus shows a solid underline on the label. An
+ * `icon-only` button has no visible text, so always set `accessible-label`
+ * (not `aria-label`, which isn't forwarded into the shadow root).
+ *
+ * **Look:** set by tokens — `stroke.control` (border width), `shape.control`
+ * (corners), `typography.control.*` (type), `button.variant.<variant>.*`
+ * (background, text, border and shadow colour per state), `button.size.<size>.*`
+ * (font size, padding, minimum height), `elevation.offset.*` (shadow offset)
+ * and `lift.hoverMd` / `lift.pressMd` (movement on hover and press).
+ *
+ * @element oh-button
+ * @fires oh-click - The button was clicked (not while loading). `detail.originalEvent` is the click.
+ * @slot - The label.
+ * @slot icon-left - An icon before the label.
+ * @slot icon-right - An icon after the label.
+ * @csspart button - The inner `<button>` or `<a>`.
+ */
 let OhButton = class OhButton extends OhElement {
     constructor() {
         super(...arguments);
@@ -45,7 +71,7 @@ let OhButton = class OhButton extends OhElement {
         this.loading = false;
         this.iconOnly = false;
         /**
-         * Force a visual state (for documentation/Figma sync only)
+         * Force a visual state (for documentation only)
          * Values: 'hover' | 'active' | 'focus'
          */
         this.forceState = "default";
@@ -53,17 +79,12 @@ let OhButton = class OhButton extends OhElement {
     static { this.styles = [
         baseStyles,
         css `
-      /* ═══════════════════════════════════════════════════════════════
-         ORANGE HALO BUTTON
-         Chunky • Playful • Confident • Hand-crafted
-         ═══════════════════════════════════════════════════════════════ */
-
       :host {
         display: inline-block;
       }
 
       .button {
-        /* Typography: friendly, not shouty */
+        /* Typography: button.base.* (from typography.control.*) */
         font-family: var(--oh-button-base-font-family);
         font-weight: var(--oh-button-base-font-weight);
         letter-spacing: var(--oh-button-base-letter-spacing);
@@ -75,10 +96,10 @@ let OhButton = class OhButton extends OhElement {
         justify-content: center;
         gap: var(--oh-spacing-2);
 
-        /* Shape: chunky rounded corners, not pills */
+        /* Corners: button.base.borderRadius (shape.control) */
         border-radius: var(--oh-button-base-border-radius);
 
-        /* Thick illustrative border */
+        /* Border width: button.base.borderWidth (stroke.control) */
         border: var(--oh-button-base-border-width) solid;
 
         /* Remove default button styles */
@@ -87,18 +108,16 @@ let OhButton = class OhButton extends OhElement {
         -moz-appearance: none;
         appearance: none;
 
-        /* Smooth but snappy transitions */
+        /* Transitions: motion.snappy / motion.quick */
         transition:
-          transform var(--oh-motion-snappy) var(--oh-motion-ease-playful),
-          box-shadow var(--oh-motion-snappy) var(--oh-motion-ease-playful),
+          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;
       }
 
       /* ═══════════════════════════════════════════════════════════════
          PRIMARY VARIANT
-         Signature orange — bold and warm
-         Filled button: color + shadow define shape (no visible border)
-         Contrast: white on brand primary = 5.0:1 ✓ (WCAG AA)
+         Filled: button.variant.primary.* (border matches the fill)
          ═══════════════════════════════════════════════════════════════ */
 
       .button--primary {
@@ -106,7 +125,7 @@ let OhButton = class OhButton extends OhElement {
         border-color: var(--oh-button-variant-primary-border-color);
         color: var(--oh-button-variant-primary-color);
 
-        /* Light offset shadow: makes button pop forward */
+        /* Offset shadow: elevation.offset.lg at rest */
         box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg)
           0 0 var(--oh-button-variant-primary-shadow-color);
       }
@@ -130,7 +149,8 @@ let OhButton = class OhButton extends OhElement {
 
       /* ═══════════════════════════════════════════════════════════════
          SECONDARY VARIANT
-         Light button: NEEDS visible border for definition
+         button.variant.secondary.*: its border (borderColor) defines the
+         button's edge against the page, so it must stay visible
          ═══════════════════════════════════════════════════════════════ */
 
       .button--secondary {
@@ -159,8 +179,7 @@ let OhButton = class OhButton extends OhElement {
 
       /* ═══════════════════════════════════════════════════════════════
          ACCENT VARIANT
-         Calm blue — modern counterbalance to warm orange
-         Filled button: color + shadow define shape (no visible border)
+         Filled: button.variant.accent.* (border matches the fill)
          ═══════════════════════════════════════════════════════════════ */
 
       .button--accent {
@@ -217,8 +236,8 @@ let OhButton = class OhButton extends OhElement {
 
       /* ═══════════════════════════════════════════════════════════════
          SIZE VARIANTS
-         Minimum 16px (1rem) for WCAG readability
-         Values: button.size.* tokens
+         Values: button.size.* tokens. Font sizes come from
+         typography.control.fontSize.*, never below font.size.base
          ═══════════════════════════════════════════════════════════════ */
 
       .button--sm {
@@ -289,7 +308,7 @@ let OhButton = class OhButton extends OhElement {
         content: "";
         position: absolute;
         bottom: 4px;
-        left: 50%;
+        left: 50%; /* physical: centred, with the translate below */
         transform: translateX(-50%);
         width: 60%;
         height: 2px;
@@ -363,7 +382,7 @@ let OhButton = class OhButton extends OhElement {
       }
 
       /* ═══════════════════════════════════════════════════════════════
-         FORCED STATES (for Figma Sync / documentation)
+         FORCED STATES (for documentation)
          ═══════════════════════════════════════════════════════════════ */
 
       /* Primary - Forced Hover */

package/dist/oh-button.js.map

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

package/dist/oh-card.d.ts

@@ -1,37 +1,65 @@
 /**
  * oh-card
  *
- * A tactile, raised surface with visible frame.
- * Designed with the same layered construction as oh-button.
+ * A surface that groups related content, with optional header and footer.
  *
  * DESIGN DECISIONS:
  * ─────────────────
- * 1. LAYERED CONSTRUCTION
- *    - Surface: subtle gradient for depth
- *    - Border: visible warm edge
- *    - Inner highlight: sunlit top edge
- *    - Outer shadow: soft, slightly offset
- *
- * 2. RETRO-MODERN DETAILS
- *    - Warm, tactile shadows (never harsh)
- *    - Visible border that warms on hover
- *    - Subtle gradient background
- *
- * 3. VARIANTS
- *    - Raised: default with layered depth
- *    - Sunlit: featured with warm gradient
- *    - Flat: border-only, minimal shadow
+ * 1. THREE PARTS: header, content and footer are separate parts so each can
+ *    be styled.
  *
- * @element oh-card
+ * 2. VARIANTS BY ROLE, LOOK FROM TOKENS
+ *    - default, featured (the one card that should stand out), subtle (quieter)
+ *    - Each variant's surface, border and shadow come from its own
+ *      card.variant.<variant>.* tokens and an elevation.surface.* token, so a brand
+ *      changes the look without touching this file.
+ *
+ * 3. INTERACTIVE MODE: role="button" on the inner card, Enter/Space and
+ *    click fire oh-click. Focus is a solid focus.ring* outline; any
+ *    focus.glowColor shadow is decoration only.
+ *
+ * 4. CONTRAST: card surfaces remap color.text.link to color.text.linkRaised
+ *    so links inside keep 4.5:1.
  */
 import { OhElement } from "./base.js";
-export type CardVariant = "raised" | "sunlit" | "flat";
+export type CardVariant = "default" | "featured" | "subtle";
 export type CardPadding = "none" | "sm" | "md" | "lg";
+/**
+ * A surface that groups related content (a summary, a teaser, a settings group), with optional header and footer.
+ *
+ * **Use it for** a self-contained block of content among others, or a whole-card link to more detail (`interactive`). **Don't use it for** page layout or spacing alone (use `oh-stack`, `oh-grid`); for a message that needs attention (use `oh-alert`); or for a single action (use `oh-button`).
+ *
+ * **Variants:** `default`, the standard card; `featured`, for the one card that should stand out; `subtle`, a quieter card, for dense layouts. **Padding:** `none`, `sm`, `md` (default), `lg` set the content padding (and the header and footer padding to match). With `none`, the content sets its own padding.
+ *
+ * **States (interactive only):** rest, hover, active (pressed) and focus-visible.
+ *
+ * **Behaviour:** with `interactive`, the card is focusable (`tabindex="0"`), has `role="button"`, and fires `oh-click` on click, Enter or Space. Hover movement is turned off under `prefers-reduced-motion`.
+ *
+ * **Accessibility:** focus shows a solid outline (`focus.ringWidth`, `focus.ringColor`, `focus.ringOffset`). Links inside use `color.text.linkRaised`, which keeps contrast on card surfaces. An interactive card is one button: give it a short heading so its accessible name makes sense, and don't put other buttons or links inside it.
+ *
+ * **Look:** set by tokens. `card.variant.<variant>.gradientStart`/`gradientMid`/`gradientEnd` set each variant's surface, `card.variant.<variant>.borderColor` and `card.base.borderWidth` its border, `shape.large` the corners, and `elevation.surface.default`/`subtle`/`featured` its shadow. Hover uses `color.border.strong` (or `card.variant.featured.borderColorHover`), `elevation.surface.hover`/`featuredHover` and `lift.hoverMd`/`lift.hoverSm`; active uses `elevation.surface.active`; focus sets the border to `color.brand.primary` and adds `focus.glowColor` with `elevation.surface.focus`/`featuredFocus`. Header and footer dividers use `card.section.dividerColor` and `stroke.divider`; the header surface uses `card.section.headerGradientStart`/`End`, the footer `color.surface.raised` to `color.surface.inset`; motion uses `motion.gentle` and `motion.easeGentle`.
+ *
+ * @element oh-card
+ * @slot - The card's main content.
+ * @slot header - Optional header, above the content, with a divider below. Not drawn when nothing is slotted.
+ * @slot footer - Optional footer, below the content, with a divider above (e.g. actions). Not drawn when nothing is slotted.
+ * @csspart card - The card surface (the button when `interactive`).
+ * @csspart header - The header wrapper.
+ * @csspart content - The content wrapper.
+ * @csspart footer - The footer wrapper.
+ * @fires oh-click - When an `interactive` card is clicked or activated with Enter or Space. `detail.originalEvent` holds the source event.
+ */
 export declare class OhCard extends OhElement {
     static styles: import("lit").CSSResult[];
     variant: CardVariant;
     interactive: boolean;
     padding: CardPadding;
+    private _hasHeader;
+    private _hasFooter;
+    /** True when the slot holds an element or non-whitespace text */
+    private _slotHasContent;
+    private _onHeaderSlotChange;
+    private _onFooterSlotChange;
     private _handleClick;
     private _handleKeyDown;
     render(): import("lit").TemplateResult<1>;

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

@@ -1 +1 @@
-{"version":3,"file":"oh-card.d.ts","sourceRoot":"","sources":["../src/oh-card.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,EAAE,SAAS,EAAc,MAAM,WAAW,CAAC;AAElD,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AACvD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEtD,qBACa,MAAO,SAAQ,SAAS;IACnC,OAAgB,MAAM,4BAwOpB;IAGF,OAAO,EAAE,WAAW,CAAY;IAGhC,WAAW,UAAS;IAGpB,OAAO,EAAE,WAAW,CAAQ;IAE5B,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,cAAc;IAOtB,MAAM;CA+BP;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,SAAS,EAAE,MAAM,CAAC;KACnB;CACF"}
+{"version":3,"file":"oh-card.d.ts","sourceRoot":"","sources":["../src/oh-card.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,EAAE,SAAS,EAAc,MAAM,WAAW,CAAC;AAElD,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;AAC5D,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBACa,MAAO,SAAQ,SAAS;IACnC,OAAgB,MAAM,4BAyNpB;IAGF,OAAO,EAAE,WAAW,CAAa;IAGjC,WAAW,UAAS;IAGpB,OAAO,EAAE,WAAW,CAAQ;IAEnB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAS;IAEpC,iEAAiE;IACjE,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,cAAc;IAOtB,MAAM;CA+BP;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,SAAS,EAAE,MAAM,CAAC;KACnB;CACF"}