@adia-ai/web-components 0.0.14 → 0.0.16

package/components/option-card/option-card.a2ui.json

@@ -0,0 +1,262 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/OptionCard.json",
+  "title": "OptionCard",
+  "description": "Selectable card with radio semantics. A \"rich radio\" — single-select one of N where each option carries a heading, optional description, and optional leading icon. Siblings sharing a `name` form a radiogroup. The whole card is the click target; a CSS-rendered radio circle in the top-left signals state. Form-associated, so `name=value` submits with the parent form when checked.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "description": {
+      "description": "Description text. Stamped into a [slot=\"description\"] span when no slotted description is provided.",
+      "type": "string",
+      "default": ""
+    },
+    "required": {
+      "description": "Marks the radiogroup as requiring a selection for form validation.",
+      "type": "boolean",
+      "default": false
+    },
+    "checked": {
+      "description": "Whether this card is currently selected.",
+      "type": "boolean",
+      "default": false
+    },
+    "component": {
+      "const": "OptionCard"
+    },
+    "disabled": {
+      "description": "Disables interaction and dims the card.",
+      "type": "boolean",
+      "default": false
+    },
+    "heading": {
+      "description": "Heading text. Stamped into a [slot=\"heading\"] span when no slotted heading is provided.",
+      "type": "string",
+      "default": ""
+    },
+    "icon": {
+      "description": "Optional Phosphor icon name. Stamped as a leading <icon-ui slot=\"icon\"> when set.",
+      "type": "string",
+      "default": ""
+    },
+    "layout": {
+      "description": "Internal layout. `default` puts the indicator on the left and the icon adjacent. `tile` stacks vertically — icon top-left, indicator top-right, heading + description below — for hero pickers (source / role / plan tiles) where the icon is a primary brand cue.",
+      "type": "string",
+      "enum": [
+        "default",
+        "tile"
+      ],
+      "default": "default"
+    },
+    "name": {
+      "description": "Form control name. Siblings sharing a name form a radiogroup.",
+      "type": "string",
+      "default": ""
+    },
+    "value": {
+      "description": "Form value submitted when checked (defaults to `on` if empty).",
+      "type": "string",
+      "default": ""
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "input",
+    "events": {
+      "change": {
+        "description": "Fired when this card becomes selected (bubbles)."
+      }
+    },
+    "examples": [
+      {
+        "description": "A four-option pick-one for \"what brings you here\" — radio-card behavior with heading + description per option.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Column\",\n    \"gap\": \"2\",\n    \"children\": [\"build\", \"explore\", \"migrate\", \"evaluate\"]\n  },\n  {\n    \"id\": \"build\",\n    \"component\": \"OptionCard\",\n    \"name\": \"use-case\",\n    \"value\": \"build\",\n    \"checked\": true,\n    \"heading\": \"I'm building a product\",\n    \"description\": \"Spinning up a new project — design, ship, iterate.\"\n  },\n  {\n    \"id\": \"explore\",\n    \"component\": \"OptionCard\",\n    \"name\": \"use-case\",\n    \"value\": \"explore\",\n    \"heading\": \"I'm exploring the product\",\n    \"description\": \"Kicking the tires before bringing a team along.\"\n  },\n  {\n    \"id\": \"migrate\",\n    \"component\": \"OptionCard\",\n    \"name\": \"use-case\",\n    \"value\": \"migrate\",\n    \"heading\": \"I'm migrating from another tool\",\n    \"description\": \"Moving an existing workspace and want a smooth port.\"\n  },\n  {\n    \"id\": \"evaluate\",\n    \"component\": \"OptionCard\",\n    \"name\": \"use-case\",\n    \"value\": \"evaluate\",\n    \"heading\": \"I'm evaluating for my team\",\n    \"description\": \"Comparing options and want to dig into specifics.\"\n  }\n]",
+        "name": "use-case-picker"
+      }
+    ],
+    "keywords": [
+      "option",
+      "card",
+      "radio",
+      "select",
+      "choice",
+      "picker",
+      "tier",
+      "plan",
+      "onboarding",
+      "registration"
+    ],
+    "name": "AdiaOptionCard",
+    "related": [
+      "radio",
+      "card",
+      "check",
+      "segmented"
+    ],
+    "slots": {
+      "description": {
+        "description": "Rich description content. Overrides the `description` attribute when present."
+      },
+      "default": {
+        "description": "Spillover content revealed only when the card is checked — typically a follow-up form field (e.g. a textarea on an \"Other\" option, conditional inputs that depend on the selection). Aligns with the heading/description column; hidden via `display: none` when not checked."
+      },
+      "heading": {
+        "description": "Rich heading content. Overrides the `heading` attribute when present."
+      },
+      "icon": {
+        "description": "Custom icon element. Overrides the `icon` attribute when present."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, ready for interaction.",
+        "name": "idle"
+      },
+      {
+        "description": "Pointer over a non-checked card.",
+        "name": "hover",
+        "selector": ":not([checked]):not([disabled]):hover"
+      },
+      {
+        "description": "Selected — accent border, tinted background, filled radio circle.",
+        "attribute": "checked",
+        "name": "checked"
+      },
+      {
+        "description": "Non-interactive; dimmed.",
+        "attribute": "disabled",
+        "name": "disabled"
+      },
+      {
+        "description": "Keyboard focus ring.",
+        "name": "focused",
+        "selector": ":focus-visible"
+      }
+    ],
+    "synonyms": {
+      "picker": [
+        "option-card",
+        "radio",
+        "select"
+      ],
+      "radio": [
+        "option-card",
+        "radio",
+        "select"
+      ],
+      "tier": [
+        "option-card",
+        "card",
+        "plan"
+      ]
+    },
+    "tag": "option-card-ui",
+    "tokens": {
+      "--option-card-bg": {
+        "description": "Default background."
+      },
+      "--option-card-bg-checked": {
+        "description": "Background when checked."
+      },
+      "--option-card-bg-hover": {
+        "description": "Hover background (non-checked)."
+      },
+      "--option-card-border": {
+        "description": "Default border color."
+      },
+      "--option-card-border-checked": {
+        "description": "Border color when checked."
+      },
+      "--option-card-border-hover": {
+        "description": "Hover border color (non-checked)."
+      },
+      "--option-card-desc-color": {
+        "description": "Description text color."
+      },
+      "--option-card-desc-line-height": {
+        "description": "Description line height."
+      },
+      "--option-card-desc-size": {
+        "description": "Description font size."
+      },
+      "--option-card-disabled-opacity": {
+        "description": "Opacity multiplier when disabled."
+      },
+      "--option-card-duration": {
+        "description": "Transition duration for hover / checked state changes."
+      },
+      "--option-card-easing": {
+        "description": "Transition easing."
+      },
+      "--option-card-focus-ring": {
+        "description": "Focus ring (box-shadow value)."
+      },
+      "--option-card-gap-x": {
+        "description": "Horizontal gap between indicator (and icon) and content."
+      },
+      "--option-card-gap-y": {
+        "description": "Vertical gap between heading and description."
+      },
+      "--option-card-heading-color": {
+        "description": "Heading text color."
+      },
+      "--option-card-heading-color-checked": {
+        "description": "Heading text color when the card is checked (defaults to `--a-fg-strong` so the selected card reads with extra emphasis on top of the bg/border state)."
+      },
+      "--option-card-heading-size": {
+        "description": "Heading font size."
+      },
+      "--option-card-heading-weight": {
+        "description": "Heading font weight."
+      },
+      "--option-card-icon-color": {
+        "description": "Leading icon color when the card is not checked."
+      },
+      "--option-card-icon-color-checked": {
+        "description": "Leading icon color when the card is checked."
+      },
+      "--option-card-icon-size": {
+        "description": "Leading icon size (sets `--a-icon-size` on the slotted icon-ui)."
+      },
+      "--option-card-padding-block": {
+        "description": "Vertical padding inside the card."
+      },
+      "--option-card-padding-inline": {
+        "description": "Horizontal padding inside the card."
+      },
+      "--option-card-radio-bg": {
+        "description": "Indicator background when not checked."
+      },
+      "--option-card-radio-border": {
+        "description": "Indicator border when not checked."
+      },
+      "--option-card-radio-dot": {
+        "description": "Inner dot color when checked."
+      },
+      "--option-card-radio-fill": {
+        "description": "Indicator fill color when checked."
+      },
+      "--option-card-radio-size": {
+        "description": "Diameter of the indicator circle."
+      },
+      "--option-card-radius": {
+        "description": "Card corner radius."
+      }
+    },
+    "traits": [
+      "focusable"
+    ],
+    "version": 1
+  }
+}

package/components/option-card/option-card.css

@@ -0,0 +1,215 @@
+@scope (option-card-ui) {
+  :where(:scope) {
+    /* ── Container ── */
+    --option-card-padding-block:    var(--a-space-3);
+    --option-card-padding-inline:   var(--a-space-4);
+    --option-card-radius:           var(--a-radius-md);
+    --option-card-bg:               var(--a-bg);
+    --option-card-border:           var(--a-border);
+    --option-card-gap-x:            var(--a-space-3);
+    --option-card-gap-y:            var(--a-space-1);
+
+    /* ── State: hover ── */
+    --option-card-bg-hover:         var(--a-bg-muted);
+    --option-card-border-hover:     var(--a-fg-subtle);
+
+    /* ── State: checked ── */
+    --option-card-bg-checked:       var(--a-accent-muted);
+    --option-card-border-checked:   var(--a-accent);
+
+    /* ── Indicator (CSS radio circle, same size + recipe as <radio-ui>). */
+    --option-card-radio-size:       var(--a-toggle-size);
+    --option-card-radio-bg:         var(--a-bg);
+    --option-card-radio-border:     var(--a-border);
+    --option-card-radio-fill:       var(--a-accent);
+    --option-card-radio-dot:        var(--a-accent-fg);
+
+    /* ── Typography ── */
+    --option-card-heading-color:          var(--a-fg);
+    --option-card-heading-color-checked:  var(--a-fg-strong);
+    --option-card-heading-weight:         var(--a-weight-medium);
+    --option-card-heading-size:           var(--a-ui-size);
+    --option-card-desc-color:             var(--a-fg-muted);
+    --option-card-desc-size:              var(--a-ui-sm);
+    --option-card-desc-line-height:       1.4;
+    --option-card-icon-color:             var(--a-fg-subtle);
+    --option-card-icon-color-checked:     var(--a-fg-strong);
+    --option-card-icon-size:              1.5rem;
+
+    /* ── State: disabled ── */
+    --option-card-disabled-opacity: 0.6;
+
+    /* ── Focus ── */
+    --option-card-focus-ring:       var(--a-focus-ring);
+
+    /* ── Transitions ── */
+    --option-card-duration:         var(--a-duration-fast);
+    --option-card-easing:           var(--a-easing);
+  }
+
+  /* ── Base — grid: indicator | (heading + description). Optional icon
+       sits between indicator and heading via :has() rules below. ── */
+  :scope {
+    box-sizing: border-box;
+    display: grid;
+    grid-template-columns: auto minmax(0, 1fr);
+    grid-template-areas:
+      "indicator heading"
+      "indicator description";
+    column-gap: var(--option-card-gap-x);
+    row-gap: var(--option-card-gap-y);
+    padding: var(--option-card-padding-block) var(--option-card-padding-inline);
+    border: 1px solid var(--option-card-border);
+    border-radius: var(--option-card-radius);
+    background: var(--option-card-bg);
+    cursor: pointer;
+    user-select: none;
+    outline: none;
+    transition:
+      background var(--option-card-duration) var(--option-card-easing),
+      border-color var(--option-card-duration) var(--option-card-easing);
+  }
+
+  /* When an icon slot is present, insert a third column for it
+     between indicator and heading. */
+  :scope:has(> [slot="icon"]) {
+    grid-template-columns: auto auto minmax(0, 1fr);
+    grid-template-areas:
+      "indicator icon heading"
+      "indicator icon description";
+  }
+  :scope > [slot="icon"] {
+    grid-area: icon;
+    align-self: start;
+    color: var(--option-card-icon-color);
+    --a-icon-size: var(--option-card-icon-size);
+    transition: color var(--option-card-duration) var(--option-card-easing);
+  }
+
+  /* ── Indicator — pure CSS radio circle, no separate <radio-ui>. */
+  :scope::before {
+    content: '';
+    grid-area: indicator;
+    width: var(--option-card-radio-size);
+    height: var(--option-card-radio-size);
+    border: 1.5px solid var(--option-card-radio-border);
+    border-radius: var(--a-radius-full);
+    background: var(--option-card-radio-bg);
+    align-self: start;
+    margin-block-start: 0.125rem;
+    flex-shrink: 0;
+    transition:
+      background var(--option-card-duration) var(--option-card-easing),
+      border-color var(--option-card-duration) var(--option-card-easing);
+  }
+
+  /* ── Slots — heading + description ── */
+  :scope > [slot="heading"] {
+    grid-area: heading;
+    color: var(--option-card-heading-color);
+    font-weight: var(--option-card-heading-weight);
+    font-size: var(--option-card-heading-size);
+    transition: color var(--option-card-duration) var(--option-card-easing);
+  }
+  :scope > [slot="description"] {
+    grid-area: description;
+    color: var(--option-card-desc-color);
+    font-size: var(--option-card-desc-size);
+    line-height: var(--option-card-desc-line-height);
+  }
+
+  /* ── Default slot — "spillover" content revealed when checked.
+       Aligns with the heading/description column (skips the indicator
+       gutter). Common pattern: an "Other" option with a free-text
+       textarea, conditional follow-up fields, etc. ── */
+  :scope > :not([slot]) {
+    grid-column: 2 / -1;
+    margin-block-start: var(--a-space-3);
+    display: none;
+  }
+  :scope:has(> [slot="icon"]) > :not([slot]) {
+    grid-column: 3 / -1;
+  }
+  :scope[checked] > :not([slot]) {
+    display: block;
+  }
+
+  /* ── State: hover (not checked, not disabled) ── */
+  :scope:not([checked]):not([disabled]):hover {
+    background: var(--option-card-bg-hover);
+    border-color: var(--option-card-border-hover);
+  }
+
+  /* ── State: checked — accent border + tinted bg + filled radio.
+       The indicator becomes an accent disc with a centered dot of
+       --option-card-radio-dot at 60% of the size, mirroring
+       radio-ui's recipe (radio.css:75-78). Done with a radial
+       gradient so a single pseudo-element carries both layers. */
+  :scope[checked] {
+    background: var(--option-card-bg-checked);
+    border-color: var(--option-card-border-checked);
+  }
+  :scope[checked]::before {
+    border-color: var(--option-card-radio-fill);
+    background:
+      radial-gradient(
+        circle,
+        var(--option-card-radio-dot) 0 30%,
+        var(--option-card-radio-fill) 30% 100%
+      );
+  }
+  /* Heading + icon shift to a strong color when checked — gives the
+     selected card a clear text-level emphasis on top of the bg/border
+     state, so picking is unambiguous beyond the radio dot alone. */
+  :scope[checked] > [slot="heading"] {
+    color: var(--option-card-heading-color-checked);
+  }
+  :scope[checked] > [slot="icon"] {
+    color: var(--option-card-icon-color-checked);
+  }
+
+  /* ── Layout: tile — icon top-left, indicator top-right, heading +
+       description below, all left-aligned. Used for hero pickers
+       (data source, role, plan tiles) where the icon is a primary
+       brand cue rather than secondary chrome. ── */
+  :scope[layout="tile"] {
+    grid-template-columns: minmax(0, 1fr) auto;
+    grid-template-areas:
+      "icon       indicator"
+      "heading    heading"
+      "description description";
+    column-gap: var(--option-card-gap-x);
+    row-gap: var(--option-card-gap-y);
+    padding: var(--a-space-4);
+    align-items: start;
+  }
+  :scope[layout="tile"] > [slot="icon"] {
+    grid-area: icon;
+    justify-self: start;
+    align-self: start;
+    --option-card-icon-size: 1.75rem;
+  }
+  :scope[layout="tile"]::before {
+    grid-area: indicator;
+    align-self: start;
+    justify-self: end;
+    margin-block-start: 0;
+  }
+  :scope[layout="tile"] > [slot="heading"] {
+    margin-block-start: var(--a-space-2);
+  }
+  :scope[layout="tile"] > :not([slot]) {
+    grid-column: 1 / -1;
+  }
+
+  /* ── State: disabled ── */
+  :scope[disabled] {
+    cursor: not-allowed;
+    opacity: var(--option-card-disabled-opacity);
+  }
+
+  /* ── Focus ── */
+  :scope:focus-visible {
+    box-shadow: var(--option-card-focus-ring);
+  }
+}

package/components/option-card/option-card.js

@@ -0,0 +1,158 @@
+/**
+ * <option-card-ui> — Selectable card with radio semantics.
+ *
+ * A "rich radio" — single-select-of-N where each option carries a
+ * heading, optional description, and optional leading icon. Siblings
+ * with the same `name` form a radiogroup. The whole card is the click
+ * target; a CSS-rendered radio circle in the top-left signals state.
+ *
+ *   <option-card-ui name="use-case" value="build" checked
+ *                   heading="I'm building a product"
+ *                   description="Spinning up a new project — design, ship, iterate.">
+ *   </option-card-ui>
+ *
+ * Rich content via slots:
+ *
+ *   <option-card-ui name="plan" value="pro">
+ *     <span slot="heading">Pro <badge-ui text="14-day trial"></badge-ui></span>
+ *     <span slot="description">Unlimited members · advanced charts</span>
+ *   </option-card-ui>
+ *
+ * Spillover content via the default slot — any unslotted child shows
+ * only when the card is `[checked]`. Used for "Other"-style fields:
+ *
+ *   <option-card-ui name="reason" value="other"
+ *                   heading="Something else">
+ *     <textarea-ui name="reason-detail" rows="3"></textarea-ui>
+ *   </option-card-ui>
+ *
+ * Sibling navigation: arrow keys move focus and selection; Space/Enter
+ * select. Form-associated via AdiaFormElement, so `name=value` submits
+ * with the parent form when the card is checked.
+ */
+
+import { AdiaFormElement } from '../../core/form.js';
+
+class AdiaOptionCard extends AdiaFormElement {
+  static properties = {
+    ...AdiaFormElement.properties,
+    checked:     { type: Boolean, default: false, reflect: true },
+    heading:     { type: String,  default: '', reflect: true },
+    description: { type: String,  default: '', reflect: true },
+    icon:        { type: String,  default: '', reflect: true },
+    layout:      { type: String,  default: 'default', reflect: true },
+  };
+
+  static template = () => null;
+
+  connected() {
+    super.connected();
+    this.setAttribute('role', 'radio');
+    this.setAttribute('tabindex', '0');
+    this.#ensureLayout();
+    this.addEventListener('click', this.#select);
+    this.addEventListener('keydown', this.#onKey);
+  }
+
+  disconnected() {
+    super.disconnected();
+    this.removeEventListener('click', this.#select);
+    this.removeEventListener('keydown', this.#onKey);
+  }
+
+  render() {
+    this.setAttribute('aria-checked', String(this.checked));
+    if (this.disabled) this.setAttribute('aria-disabled', 'true');
+    else this.removeAttribute('aria-disabled');
+
+    // Keep slotted content in sync with attrs (only when slot was
+    // auto-stamped from the attr — don't clobber consumer-authored
+    // rich content).
+    const h = this.querySelector(':scope > [slot="heading"]');
+    if (h && h.dataset.fromAttr === 'true') h.textContent = this.heading || '';
+    const d = this.querySelector(':scope > [slot="description"]');
+    if (d && d.dataset.fromAttr === 'true') d.textContent = this.description || '';
+    const i = this.querySelector(':scope > [slot="icon"]');
+    if (i && i.dataset.fromAttr === 'true') i.setAttribute('name', this.icon || '');
+
+    if (this.checked) this.syncValue(this.value || 'on');
+    else this.syncValue('');
+  }
+
+  // ── Private ───────────────────────────────────────────────────────
+
+  /** Stamp heading / description / icon from attributes when the
+   *  consumer hasn't already provided slotted content. */
+  #ensureLayout() {
+    if (this.heading && !this.querySelector(':scope > [slot="heading"]')) {
+      const el = document.createElement('span');
+      el.setAttribute('slot', 'heading');
+      el.dataset.fromAttr = 'true';
+      el.textContent = this.heading;
+      this.appendChild(el);
+    }
+    if (this.description && !this.querySelector(':scope > [slot="description"]')) {
+      const el = document.createElement('span');
+      el.setAttribute('slot', 'description');
+      el.dataset.fromAttr = 'true';
+      el.textContent = this.description;
+      this.appendChild(el);
+    }
+    if (this.icon && !this.querySelector(':scope > [slot="icon"]')) {
+      const el = document.createElement('icon-ui');
+      el.setAttribute('slot', 'icon');
+      el.dataset.fromAttr = 'true';
+      el.setAttribute('name', this.icon);
+      this.appendChild(el);
+    }
+  }
+
+  #select = () => {
+    if (this.disabled || this.readonly || this.checked) return;
+    const group = this.#group();
+    if (group) {
+      for (const el of group.querySelectorAll(`option-card-ui[name="${this.name}"]`)) {
+        if (el !== this && el.checked) el.checked = false;
+      }
+    }
+    this.checked = true;
+    this.dispatchEvent(new Event('change', { bubbles: true }));
+  };
+
+  #onKey = (e) => {
+    // Don't intercept keys when focus is in a nested form control
+    // (textarea, input, contenteditable). Otherwise Space/Enter would
+    // block typing and arrow keys would navigate siblings instead of
+    // moving the cursor.
+    if (e.target !== this) return;
+    if (e.key === ' ' || e.key === 'Enter') { e.preventDefault(); this.#select(); return; }
+    if (e.key === 'ArrowDown' || e.key === 'ArrowRight') {
+      e.preventDefault();
+      const next = this.#sibling(1);
+      if (next) { next.focus(); next.click(); }
+    }
+    if (e.key === 'ArrowUp' || e.key === 'ArrowLeft') {
+      e.preventDefault();
+      const prev = this.#sibling(-1);
+      if (prev) { prev.focus(); prev.click(); }
+    }
+  };
+
+  /** The radiogroup root — explicit `<fieldset>` / `[role="radiogroup"]`
+   *  if present, else the immediate parent. */
+  #group() {
+    return this.closest('fieldset, [role="radiogroup"]') || this.parentElement;
+  }
+
+  #sibling(dir) {
+    const group = this.#group();
+    const items = [...(group?.querySelectorAll(`option-card-ui[name="${this.name}"]`) || [])];
+    const i = items.indexOf(this);
+    if (i < 0) return null;
+    return items[(i + dir + items.length) % items.length] || null;
+  }
+}
+
+customElements.define('option-card-ui', AdiaOptionCard);
+
+export { AdiaOptionCard };