@reliability-design/web 1.4.6 → 1.4.8

package/dist/components/rel-card/README.md

@@ -1,94 +1,75 @@
-# rel-card
-
-## Overview
-A simple, versatile card container component with built-in elevation shadow and hover lift effect. Provides a clean, elevated surface for grouping related content. Respects user motion preferences by disabling animations when requested.
-
-## Usage
-```html
-<!-- Basic card with text content -->
-<rel-card>
-  <h3>Card Title</h3>
-  <p>This is some content inside the card.</p>
-</rel-card>
-
-<!-- Card with mixed content -->
-<rel-card>
-  <h2>Product Name</h2>
-  <img src="product.jpg" alt="Product" style="width: 100%; border-radius: 8px;">
-  <p>Product description goes here.</p>
-  <button>Add to Cart</button>
-</rel-card>
-
-<!-- Multiple cards in a grid -->
-<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px;">
-  <rel-card>
-    <h4>Feature 1</h4>
-    <p>Description of feature 1</p>
-  </rel-card>
-  <rel-card>
-    <h4>Feature 2</h4>
-    <p>Description of feature 2</p>
-  </rel-card>
-  <rel-card>
-    <h4>Feature 3</h4>
-    <p>Description of feature 3</p>
-  </rel-card>
-</div>
-```
-
-## API
-
-### Attributes/Properties
-None. This component is purely presentational and controlled via slots.
-
-## Events
-None.
-
-## Slots
-| Slot | Description |
-|------|-------------|
-| (default) | Card content (any HTML elements) |
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-
-### Color Tokens
-- `--rel-bg-surface` - Card background color
-- `--rel-text-default` - Text color
-
-### Shadow Tokens
-- `--rel-shadows-shadow-200` - Default elevation shadow
-- `--rel-shadows-shadow-300` - Hover elevation shadow (larger)
-
-### Border Tokens
-- `--rel-border-radius-md` - Card border radius
-
-### Spacing Tokens
-- `--rel-spacing-md` - Internal padding
-
-## Accessibility
-- The card itself has no specific ARIA role (it's a generic container)
-- Ensure slotted content includes proper semantic HTML and ARIA attributes where needed
-- Hover effect is purely visual and does not affect accessibility
-
-### Keyboard Interactions
-- None (purely presentational container)
-
-### Focus Behavior
-- Does not receive focus (container only)
-- Ensure slotted interactive elements are keyboard accessible
-
-## Notes / Edge Cases
-- The card is `display: block` and takes full width of its container by default
-- **Hover effect**: Translates the card upward by 3px (`translateY(-3px)`) and increases shadow depth
-- **Animation**: Uses `transition: transform 0.2s ease, box-shadow 0.2s ease`
-- **Motion preferences**: When `prefers-reduced-motion: reduce`, both hover transform and transitions are disabled
-- The card has consistent padding on all sides via `--rel-spacing-md`
-- The internal `.card` wrapper is where all styling is applied
-- The component provides no default content styling—you control the layout of slotted elements
-- Works well with CSS Grid or Flexbox for creating card layouts
+# rel-card
+
+`<rel-card>` is an elevated, padded surface that groups related content — the Figma "Card" component. `type="custom"` (the default) pads whatever you slot in and applies the Figma card typography to slotted headings and paragraphs; `type="media"` adds a flush media region above the body, meant for a `<rel-card-media>` image header. Use it for dashboard tiles, summary blocks and list items that pair a title with body copy. It is a static container with no interaction of its own — for transient content use `rel-modal` or `rel-drawer` instead, and for a surface with its own tone/elevation variants use `rel-container`.
+
+## Usage
+
+```html
+<!-- Default type: padded body -->
+<rel-card>
+  <h3>Shipment 4821</h3>
+  <p>Departed Dallas · ETA Thursday 14:00</p>
+</rel-card>
+
+<!-- Media type: flush image header via <rel-card-media> in the "media" slot -->
+<rel-card type="media">
+  <rel-card-media slot="media" image-src="/img/warehouse.jpg" image-alt="Warehouse floor"></rel-card-media>
+  <h3>Dallas hub</h3>
+  <p>12 dock doors · 24/7 operations</p>
+</rel-card>
+
+<!-- Cards in a grid -->
+<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px;">
+  <rel-card><h4>On time</h4><p>98.2%</p></rel-card>
+  <rel-card><h4>Damage-free</h4><p>99.7%</p></rel-card>
+  <rel-card><h4>Claims</h4><p>3 open</p></rel-card>
+</div>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-card.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `type` | `type` | `"custom" \| "media"` | `"custom"` | Figma "Type" axis: custom (default) renders slotted content with card padding; media adds a flush media region (slot name="media") above the content — pair it with <rel-card-media>. Reflected. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Card body; slotted headings and paragraphs receive the Figma card typography |
+| `media` | Flush media region above the body; rendered only when `type="media"` |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The outer elevated card surface |
+| `header` | The media region wrapper (present only when `type="media"`) |
+| `content` | The padded body that wraps the default slot |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The card sets no ARIA role — it is a generic container (`display: block`), so the accessible structure comes entirely from the slotted content. Use real headings (`<h2>`–`<h4>`) and paragraphs inside it; they also pick up the card typography.
+- The host is not focusable and has no keyboard handling. Interactive children (links, `rel-button`) keep their own focus order and must be keyboard-reachable on their own.
+- A `<rel-card-media>` in the `media` slot carries the image's alt text via its `image-alt` attribute; leave it empty only for purely decorative imagery.
+
+## Notes / Edge Cases
+
+- `type="media"` removes the card's own padding and clips overflow so the media sits flush against the rounded border; the body (`content` part) keeps the standard padding. Content placed in the `media` slot without `type="media"` is not rendered, because the slot only exists in that mode.
+- The `header` part exists only while `type="media"`; `::part(header)` matches nothing otherwise.
+- Slotted `h1`–`h4` and `p` elements get the Figma card roles (heading md / body lg) with their default margins reset; wrap other content in your own elements to style it.
+- The card is elevated with Figma's `shadow/sm` and draws no border, in both light and dark themes. There is no hover lift or transition.

package/dist/components/rel-cardmedia/README.md

@@ -1,127 +1,100 @@
-# rel-card-media
-
-## Overview
-A media-rich card component combining an image, title, subtitle, and custom content area. Features automatic image sizing with object-fit, enhanced hover lift effect (4px), and semantic heading structure. Ideal for blog posts, product listings, or media galleries.
-
-## Usage
-```html
-<!-- Basic media card -->
-<rel-card-media
-  imageSrc="./photo.jpg"
-  imageAlt="Beautiful landscape"
-  title="Card Title"
-  subtitle="Card subtitle or description">
-</rel-card-media>
-
-<!-- With custom slotted content -->
-<rel-card-media
-  imageSrc="./product.jpg"
-  imageAlt="Product image"
-  title="Premium Product"
-  subtitle="$99.99">
-  <p>Additional product details go here.</p>
-  <button>Buy Now</button>
-</rel-card-media>
-
-<!-- Without image -->
-<rel-card-media
-  title="Text-Only Card"
-  subtitle="No image provided">
-  <p>This card has no image, just title, subtitle, and content.</p>
-</rel-card-media>
-
-<!-- With title only -->
-<rel-card-media
-  imageSrc="./banner.jpg"
-  imageAlt="Banner"
-  title="Event Title">
-  <p>Event description and details.</p>
-</rel-card-media>
-
-<!-- Gallery layout -->
-<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 20px;">
-  <rel-card-media
-    imageSrc="./img1.jpg"
-    title="Gallery Item 1">
-  </rel-card-media>
-  <rel-card-media
-    imageSrc="./img2.jpg"
-    title="Gallery Item 2">
-  </rel-card-media>
-  <rel-card-media
-    imageSrc="./img3.jpg"
-    title="Gallery Item 3">
-  </rel-card-media>
-</div>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `imageSrc` | `string` | `""` | URL of the card image (optional) |
-| `imageAlt` | `string` | `"Card image"` | Alt text for the image (for accessibility) |
-| `title` | `string` | `""` | Card title displayed as `<h3>` (optional) |
-| `subtitle` | `string` | `""` | Card subtitle displayed as `<p>` (optional) |
-
-## Events
-None.
-
-## Slots
-| Slot | Description |
-|------|-------------|
-| (default) | Additional content rendered below title and subtitle |
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-- `--rel-body-md-regular-font-size` - Title font size
-- `--rel-body-sm-regular-font-size` - Subtitle font size
-- `--rel-fonts-weight-body-semibold` - Title font weight
-
-### Color Tokens
-- `--rel-bg-surface` - Card background color
-- `--rel-text-default` - General text color
-- `--rel-text-label` - Title color
-
-### Shadow Tokens
-- `--rel-shadows-shadow-200` - Default elevation shadow
-- `--rel-shadows-shadow-300` - Hover elevation shadow (larger)
-
-### Border Tokens
-- `--rel-border-radius-md` - Card border radius
-
-### Spacing Tokens
-- `--rel-spacing-md` - Content area padding
-
-## Accessibility
-- Image has `alt` attribute for screen reader support
-- Title uses semantic `<h3>` heading
-- Subtitle uses `<p>` for proper text hierarchy
-- Hover effect is purely visual and does not affect accessibility
-
-### Keyboard Interactions
-- None (purely presentational container)
-- Ensure slotted interactive elements are keyboard accessible
-
-### Focus Behavior
-- Does not receive focus (container only)
-
-## Notes / Edge Cases
-- **Image rendering**: If `imageSrc` is not provided or empty, the image section is not rendered
-- **Image sizing**: The image uses `width: 100%`, `height: auto`, and `object-fit: cover` for responsive scaling
-- The image is `display: block` to remove default inline spacing
-- **Title and subtitle**: Both are optional; if not provided, their respective elements are not rendered
-- Title has `margin: 0 0 4px 0` for spacing from subtitle
-- Subtitle has `margin: 0 0 8px 0` for spacing from slotted content
-- **Hover effect**: Translates the card upward by 4px (`translateY(-4px)`) and increases shadow depth (1px more than rel-card)
-- **Animation**: Uses `transition: transform 0.2s ease, box-shadow 0.2s ease`
-- **Motion preferences**: When `prefers-reduced-motion: reduce`, both hover transform and transitions are disabled
-- The card uses `overflow: hidden` to ensure image respects border radius
-- The `.card-content` wrapper provides consistent padding for title, subtitle, and slotted content
-- The component is `display: block` and takes full width of its container
+# rel-card-media
+
+Media card (element `<rel-card-media>`, folder `rel-cardmedia`): a bordered surface with an optional full-width image on top, then a title (`<h3>`), a subtitle and a slotted body inside a padded content area. Use it for previews that lead with an image — articles, products, gallery tiles. Use `rel-card` when you need a free-form layout or no image section.
+
+## Usage
+
+```html
+<!-- Image, title, subtitle -->
+<rel-card-media
+  image-src="/images/lake.jpg"
+  image-alt="A mountain lake at sunrise"
+  title="Alpine lakes"
+  subtitle="12 photos"
+></rel-card-media>
+
+<!-- With slotted body content -->
+<rel-card-media
+  image-src="/images/headphones.jpg"
+  image-alt="Over-ear headphones"
+  title="Studio headphones"
+  subtitle="$99.99"
+>
+  <p>Closed-back, 40 mm drivers, detachable cable.</p>
+  <rel-button variant="primary" size="small">Add to cart</rel-button>
+</rel-card-media>
+
+<!-- No image: just the content area -->
+<rel-card-media title="Text-only card" subtitle="No image provided">
+  <p>Body copy goes in the default slot.</p>
+</rel-card-media>
+
+<!-- Gallery grid -->
+<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 20px;">
+  <rel-card-media image-src="/images/1.jpg" image-alt="" title="Item 1"></rel-card-media>
+  <rel-card-media image-src="/images/2.jpg" image-alt="" title="Item 2"></rel-card-media>
+  <rel-card-media image-src="/images/3.jpg" image-alt="" title="Item 3"></rel-card-media>
+</div>
+
+<!-- Restyle through parts -->
+<style>
+  .flat::part(base) {
+    border: none;
+  }
+  .flat::part(content) {
+    padding: 24px;
+  }
+</style>
+<rel-card-media class="flat" title="Flat card"></rel-card-media>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-cardmedia.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `imageSrc` | `image-src` | `string` | `""` | URL of the hero image shown full-width at the top of the card. Empty (the default) omits the image section entirely. |
+| `imageAlt` | `image-alt` | `string` | `"Card image"` | Alternative text for the hero image. Replace the generic default with a real description, or an empty string for purely decorative images. |
+| `title` | `title` | `string` | `""` | Heading rendered as an `<h3>` above the subtitle; empty omits it. Note this is also the native `title` attribute, so a value shows as a browser tooltip on hover. |
+| `subtitle` | `subtitle` | `string` | `""` | Secondary line rendered as a paragraph under the title; empty omits it. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Body content rendered inside the padded content area below the title and subtitle. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The outer bordered card surface (background, border, radius, overflow clip). |
+| `icon` | The image wrapper above the content, rendered only when `image-src` is set. |
+| `content` | The padded area holding the title, subtitle and slotted body. |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The image renders as an `<img>` whose `alt` is `image-alt`; the default "Card image" is a placeholder — supply a real description, or an empty `image-alt=""` when the picture is decorative.
+- The title is a real `<h3>`; make sure that fits the page's heading outline (there is no way to change the level).
+- The card itself is a non-focusable container with no keyboard handling. Slotted controls (buttons, links) keep their own focus and keyboard behaviour.
+
+## Notes / Edge Cases
+
+- **Attribute spellings are kebab-case**: `image-src` and `image-alt`. Setting `imageSrc="…"` as an HTML attribute does nothing; use the property in code (`el.imageSrc = …`).
+- **`title` is also the native tooltip attribute.** Because the property maps to the global `title` attribute, hovering the card shows the title text as a browser tooltip.
+- The image section (`icon` part) is omitted entirely when `image-src` is empty; the title and subtitle are likewise omitted when empty, so the content area may hold only slotted children.
+- The image is `width: 100%; height: auto; object-fit: cover` and the card clips overflow, so the top corners follow the card radius.
+- The card is static: no hover lift, shadow or transition is applied.