[feat] Card slots

packages/card/src/vaadin-card.js

@@ -10,14 +10,40 @@ import { PolylitMixin } from '@vaadin/component-base/src/polylit-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
 /**
- * `<vaadin-card>` is a visual content container.
+ * `<vaadin-card>` is a versatile container for grouping related content and actions.
+ * It presents information in a structured and visually appealing manner, with
+ * customization options to fit various design requirements.
  *
  * ```html
- * <vaadin-card>
- *   <div>Card content</div>
+ * <vaadin-card theme="outlined cover-media">
+ *   <img slot="media" width="200" src="..." alt="">
+ *   <div slot="title">Lapland</div>
+ *   <div slot="subtitle">The Exotic North</div>
+ *   <div>Lapland is the northern-most region of Finland and an active outdoor destination.</div>
+ *   <vaadin-button slot="footer">Book Vacation</vaadin-button>
  * </vaadin-card>
  * ```
  *
+ * ### Styling
+ *
+ * The following shadow DOM parts are available for styling:
+ *
+ * Part name | Description
+ * ----------|-------------
+ * `media`   | The container for the media element (e.g., image, video, icon). Shown above of before the card content.
+ * `header`  | The container for title and subtitle - or for custom header content - and header prefix and suffix elements.
+ * `content` | The container for the card content (usually text content).
+ * `footer`  | The container for footer elements. This part is always at the bottom of the card.
+ *
+ * The following custom properties are available for styling:
+ *
+ * Custom property | Description | Default
+ * ----------------|-------------|-------------
+ * `--vaadin-card-padding` | The space between the card edge and its content. Needs to a unified value for all edges, i.e., a single length value. | `1em`
+ * `--vaadin-card-gap`     | The space between content elements within the card. | `1em`
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
+ *
  * @customElement
  * @extends HTMLElement
  * @mixes ElementMixin
@@ -31,11 +57,233 @@ class Card extends ElementMixin(ThemableMixin(PolylitMixin(LitElement))) {
   static get styles() {
     return css`
       :host {
+        display: flex;
+        flex-direction: column;
+        padding: var(--_padding);
+        gap: var(--_gap);
+        --_padding: var(--vaadin-card-padding, 1em);
+        --_gap: var(--vaadin-card-gap, 1em);
+        --_media: 0;
+        --_title: 0;
+        --_subtitle: 0;
+        --_header: max(var(--_header-prefix), var(--_title), var(--_subtitle), var(--_header-suffix));
+        --_header-prefix: 0;
+        --_header-suffix: 0;
+        --_content: 0;
+        --_footer: 0;
+      }
+
+      :host(:not([theme~='horizontal'])) {
+        justify-content: space-between;
+      }
+
+      :host(:is(:has([slot='media']), [has-media])) {
+        --_media: 1;
+      }
+
+      :host(:is(:has([slot='title']), [has-title])) {
+        --_title: 1;
+      }
+
+      :host(:is(:has([slot='subtitle']), [has-subtitle])) {
+        --_subtitle: 1;
+      }
+
+      :host(:is(:has([slot='header']), [has-header])) {
+        --_header: 1;
+        --_title: 0;
+        --_subtitle: 0;
+      }
+
+      :host(:is(:has([slot='header-prefix']), [has-header-prefix])) {
+        --_header-prefix: 1;
+      }
+
+      :host(:is(:has([slot='header-suffix']), [has-header-suffix])) {
+        --_header-suffix: 1;
+      }
+
+      :host(:is(:has(> :not([slot])), [has-content])) {
+        --_content: 1;
+      }
+
+      :host(:is(:has([slot='footer']), [has-footer])) {
+        --_footer: 1;
+      }
+
+      [part='media'],
+      [part='header'],
+      [part='content'],
+      [part='footer'] {
+        display: none;
+      }
+
+      :host(:is(:has([slot='media']), [has-media])) [part='media'],
+      :host(:is(:has(> :not([slot])), [has-content])) [part='content'] {
         display: block;
       }
 
-      :host([hidden]) {
-        display: none !important;
+      :host(:is(:has([slot='footer']), [has-footer])) [part='footer'] {
+        display: flex;
+        gap: var(--_gap);
+      }
+
+      :host(
+          :is(
+              :has([slot='header']),
+              [has-header],
+              :has([slot='title']),
+              [has-title],
+              :has([slot='subtitle']),
+              [has-subtitle],
+              :has([slot='header-prefix']),
+              [has-header-prefix],
+              :has([slot='header-suffix']),
+              [has-header-suffix]
+            )
+        )
+        [part='header'] {
+        display: grid;
+        align-items: center;
+        gap: var(--_gap);
+        row-gap: 0;
+      }
+
+      [part='header'] {
+        margin-bottom: auto;
+      }
+
+      :host(:is(:has([slot='header-suffix']), [has-header-suffix])) [part='header'] {
+        grid-template-columns: 1fr auto;
+      }
+
+      :host(:is(:has([slot='header-prefix']), [has-header-prefix])) [part='header'] {
+        grid-template-columns: repeat(var(--_header-prefix), auto) 1fr;
+      }
+
+      slot {
+        border-radius: inherit;
+      }
+
+      ::slotted([slot='header-prefix']) {
+        grid-column: 1;
+        grid-row: 1 / span calc(var(--_title) + var(--_subtitle));
+      }
+
+      ::slotted([slot='header']),
+      ::slotted([slot='title']) {
+        grid-column: calc(1 + var(--_header-prefix));
+        grid-row: 1;
+      }
+
+      ::slotted([slot='subtitle']) {
+        grid-column: calc(1 + var(--_header-prefix));
+        grid-row: calc(1 + var(--_title));
+      }
+
+      ::slotted([slot='header-suffix']) {
+        grid-column: calc(2 + var(--_header-prefix));
+        grid-row: 1 / span calc(var(--_title) + var(--_subtitle));
+      }
+
+      /* Horizontal */
+      :host([theme~='horizontal']) {
+        display: grid;
+        grid-template-columns: repeat(var(--_media), minmax(auto, max-content)) 1fr;
+        align-items: start;
+      }
+
+      :host([theme~='horizontal']:is(:has([slot='footer']), [has-footer])) {
+        grid-template-rows: 1fr auto;
+      }
+
+      :host([theme~='horizontal']:is(:has(> :not([slot])), [has-content])) {
+        grid-template-rows: repeat(var(--_header), auto) 1fr;
+      }
+
+      [part='media'] {
+        grid-column: 1;
+        grid-row: 1 / span calc(var(--_header) + var(--_content) + var(--_footer));
+        align-self: stretch;
+        border-radius: inherit;
+      }
+
+      [part='header'] {
+        grid-column: calc(1 + var(--_media));
+        grid-row: 1;
+      }
+
+      [part='content'] {
+        grid-column: calc(1 + var(--_media));
+        grid-row: calc(1 + var(--_header));
+        flex: auto;
+        min-height: 0;
+      }
+
+      [part='footer'] {
+        grid-column: calc(1 + var(--_media));
+        grid-row: calc(1 + var(--_header) + var(--_content));
+        border-radius: inherit;
+      }
+
+      :host([theme~='horizontal']) [part='footer'] {
+        align-self: end;
+      }
+
+      :host(:not([theme~='horizontal'])) ::slotted([slot='media']:is(img, video, svg)) {
+        max-width: 100%;
+      }
+
+      ::slotted([slot='media']) {
+        vertical-align: middle;
+      }
+
+      :host(:is([theme~='cover-media'], [theme~='stretch-media']))
+        ::slotted([slot='media']:is(img, video, svg, vaadin-icon)) {
+        width: 100%;
+        height: auto;
+        aspect-ratio: var(--vaadin-card-media-aspect-ratio, 16/9);
+        object-fit: cover;
+      }
+
+      :host([theme~='horizontal']:is([theme~='cover-media'], [theme~='stretch-media'])) {
+        grid-template-columns: repeat(var(--_media), minmax(auto, 0.5fr)) 1fr;
+      }
+
+      :host([theme~='horizontal']:is([theme~='cover-media'], [theme~='stretch-media']))
+        ::slotted([slot='media']:is(img, video, svg, vaadin-icon)) {
+        height: 100%;
+        aspect-ratio: auto;
+      }
+
+      :host([theme~='cover-media']) ::slotted([slot='media']:is(img, video, svg, vaadin-icon)) {
+        margin-top: calc(var(--_padding) * -1);
+        margin-inline: calc(var(--_padding) * -1);
+        width: calc(100% + var(--_padding) * 2);
+        max-width: none;
+        border-radius: inherit;
+        border-end-end-radius: 0;
+        border-end-start-radius: 0;
+      }
+
+      :host([theme~='horizontal'][theme~='cover-media']) ::slotted([slot='media']:is(img, video, svg, vaadin-icon)) {
+        margin-inline-end: 0;
+        width: calc(100% + var(--_padding));
+        height: calc(100% + var(--_padding) * 2);
+        border-radius: inherit;
+        border-start-end-radius: 0;
+        border-end-end-radius: 0;
+      }
+
+      /* Scroller in content */
+      [part='content'] ::slotted(vaadin-scroller) {
+        margin-inline: calc(var(--_padding) * -1);
+        padding-inline: var(--_padding);
+      }
+
+      [part='content'] ::slotted(vaadin-scroller)::before,
+      [part='content'] ::slotted(vaadin-scroller)::after {
+        margin-inline: calc(var(--_padding) * -1);
       }
     `;
   }
@@ -46,7 +294,65 @@ class Card extends ElementMixin(ThemableMixin(PolylitMixin(LitElement))) {
 
   /** @protected */
   render() {
-    return html`<slot></slot>`;
+    return html`
+      <div part="media">
+        <slot name="media"></slot>
+      </div>
+      <div part="header">
+        <slot name="header-prefix"></slot>
+        <slot name="header">
+          <slot name="title"></slot>
+          <slot name="subtitle"></slot>
+        </slot>
+        <slot name="header-suffix"></slot>
+      </div>
+      <div part="content">
+        <slot></slot>
+      </div>
+      <div part="footer">
+        <slot name="footer"></slot>
+      </div>
+    `;
+  }
+
+  /** @private */
+  _mutationObserver;
+
+  /** @private */
+  _onMutation() {
+    // Chrome doesn't support `:host(:has())`, so we'll recreate that with custom attributes
+    this.toggleAttribute('has-media', this.querySelector(':scope > [slot="media"]'));
+    this.toggleAttribute('has-header', this.querySelector(':scope > [slot="header"]'));
+    this.toggleAttribute(
+      'has-title',
+      this.querySelector(':scope > [slot="title"]') && !this.querySelector(':scope > [slot="header"]'),
+    );
+    this.toggleAttribute(
+      'has-subtitle',
+      this.querySelector(':scope > [slot="subtitle"]') && !this.querySelector(':scope > [slot="header"]'),
+    );
+    this.toggleAttribute('has-header-prefix', this.querySelector(':scope > [slot="header-prefix"]'));
+    this.toggleAttribute('has-header-suffix', this.querySelector(':scope > [slot="header-suffix"]'));
+    this.toggleAttribute('has-content', this.querySelector(':scope > :not([slot])'));
+    this.toggleAttribute('has-footer', this.querySelector(':scope > [slot="footer"]'));
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+
+    if (!CSS.supports('selector(:host(:has([slot])))')) {
+      if (!this._mutationObserver) {
+        this._mutationObserver = new MutationObserver(this._onMutation.bind(this));
+      }
+      this._mutationObserver.observe(this, { childList: 'true', attributeFilter: ['slot'], subtree: true });
+      // Trigger once manually to update attributes on first render
+      this._onMutation();
+    }
+  }
+
+  disconnectedCallback() {
+    if (this._mutationObserver) this._mutationObserver.disconnect();
+    super.disconnectedCallback();
   }
 }