@spectrum-web-components/card 0.0.0-20241209155954

package/README.md

@@ -0,0 +1,291 @@
+## Description
+
+An `<sp-card>` represents a rectangular card that contains
+a variety of text and image layouts. Cards are typically used
+to encapsulate units of a data set, such as a gallery of
+image/caption pairs.
+
+### Usage
+
+[![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/card?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/card)
+[![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/card?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/card)
+[![Try it on webcomponents.dev](https://img.shields.io/badge/Try%20it%20on-webcomponents.dev-green?style=for-the-badge)](https://webcomponents.dev/edit/collection/fO75441E1Q5ZlI0e9pgq/0lwluuJO4nR1daE9dyRw/src/index.stories.js)
+
+```
+yarn add @spectrum-web-components/card
+```
+
+Import the side effectful registration of `<sp-card>` via:
+
+```
+import '@spectrum-web-components/card/sp-card.js';
+```
+
+When looking to leverage the `Card` base class as a type and/or for extension purposes, do so via:
+
+```
+import { Card } from '@spectrum-web-components/card';
+```
+
+## Example
+
+```html demo
+<sp-card heading="Card Heading" subheading="JPG Photo">
+    <img
+        slot="cover-photo"
+        src="https://picsum.photos/200/300"
+        alt="Demo Image"
+    />
+    <div slot="footer">Footer</div>
+</sp-card>
+```
+
+```html demo
+<sp-card heading="Card Title" subheading="JPG">
+    <img slot="preview" src="https://picsum.photos/200/300" alt="Demo Image" />
+    <div slot="footer">Footer</div>
+</sp-card>
+```
+
+## Heading
+
+By default, the heading for an `<sp-card>` is applied via the `heading` attribute, which is restricted to string content only. For HTML content, use the `heading` slot instead.
+
+```html demo
+<sp-card
+    subheading="JPG Photo"
+    style="--spectrum-card-body-header-height: auto;"
+>
+    <h1 slot="heading">Card Heading</h1>
+    <img alt="" slot="cover-photo" src="https://picsum.photos/200/300" />
+    <div slot="footer">Footer</div>
+</sp-card>
+```
+
+## Linking
+
+An `<sp-card>` can be provided with an `href` attribute in order for it to act as one large anchor element. When leveraging the `href` attribute, the `download`, `target` and `rel` attributes customize the card's linking behavior. Use them as follows:
+
+<!-- prettier-ignore -->
+```html
+<sp-card
+    heading="Card Title"
+    subheading="JPG"
+    href="https://opensource.adobe.com/spectrum-web-components"
+    target="_blank"
+>
+    <img slot="cover-photo" src="https://picsum.photos/200/300" alt="Demo Image" />
+</sp-card>
+```
+
+## Variants
+
+There are multiple card variants to choose from in Spectrum. The `variant`
+attribute controls the main variant of the card.
+
+### Normal
+
+Normal cards can contain a heading, a subheading, a cover photo, and a footer.
+
+```html
+<sp-card heading="Card Heading">
+    <img alt="" slot="cover-photo" src="https://picsum.photos/200/300" />
+    <span slot="subheading">JPG photo</span>
+    <div slot="footer">Footer</div>
+</sp-card>
+```
+
+### Actions
+
+Cards can be supplied an `actions` via a names slot.
+
+```html
+<sp-card heading="Card Heading" subheading="JPG Photo">
+    <img
+        slot="cover-photo"
+        src="https://picsum.photos/200/300"
+        alt="Demo Image"
+    />
+    <div slot="footer">Footer</div>
+    <sp-action-menu
+        label="More Actions"
+        slot="actions"
+        placement="bottom-end"
+        quiet
+    >
+        <sp-menu-item>Deselect</sp-menu-item>
+        <sp-menu-item>Select Inverse</sp-menu-item>
+        <sp-menu-item>Feather...</sp-menu-item>
+        <sp-menu-item>Select and Mask...</sp-menu-item>
+        <sp-menu-divider></sp-menu-divider>
+        <sp-menu-item>Save Selection</sp-menu-item>
+        <sp-menu-item disabled>Make Work Path</sp-menu-item>
+    </sp-action-menu>
+</sp-card>
+```
+
+### No Preview Image
+
+Cards with no preview image can contain a heading, a subheading, and a footer.
+
+```html demo
+<sp-card heading="Card Title" subheading="No Preview Image">
+    <div slot="footer">Footer</div>
+</sp-card>
+```
+
+### Quiet
+
+Quiet cards can contain a heading, a subheading, a cover photo, a description, and a footer.
+
+```html
+<div style="width: 208px; height: 264px">
+    <sp-card variant="quiet" heading="Card Heading" subheading="JPG Photo">
+        <img alt="" slot="preview" src="https://picsum.photos/200/300" />
+        <div slot="description">10/15/18</div>
+        <div slot="footer">Footer</div>
+    </sp-card>
+</div>
+```
+
+When leveraging the `asset` attribute, a card can be declared as representing a `file`:
+
+```html
+<div style="width: 208px; height: 264px">
+    <sp-card
+        variant="quiet"
+        heading="Card Heading"
+        subheading="JPG Photo"
+        asset="file"
+    >
+        <img alt="" slot="preview" src="https://picsum.photos/200/300" />
+        <div slot="heading">File Name</div>
+        <div slot="description">10/15/18</div>
+        <div slot="footer">Footer</div>
+    </sp-card>
+</div>
+```
+
+Or a `folder`:
+
+```html
+<div style="width: 208px; height: 264px">
+    <sp-card variant="quiet" subheading="JPG Photo" asset="folder">
+        <img alt="" slot="preview" src="https://picsum.photos/200/300" />
+        <div slot="heading">Folder Name</div>
+        <div slot="description">10/15/18</div>
+        <div slot="footer">Footer</div>
+    </sp-card>
+</div>
+```
+
+Quiet cards will also accept `actions` via a named slot.
+
+```html
+<div style="width: 208px; height: 264px">
+    <sp-card variant="quiet" heading="Card Heading" subheading="JPG Photo">
+        <img alt="" slot="preview" src="https://picsum.photos/200/300" />
+        <div slot="description">10/15/18</div>
+        <sp-action-menu
+            label="More Actions"
+            slot="actions"
+            placement="bottom-end"
+            quiet
+        >
+            <sp-menu-item>Deselect</sp-menu-item>
+            <sp-menu-item>Select Inverse</sp-menu-item>
+            <sp-menu-item>Feather...</sp-menu-item>
+            <sp-menu-item>Select and Mask...</sp-menu-item>
+            <sp-menu-divider></sp-menu-divider>
+            <sp-menu-item>Save Selection</sp-menu-item>
+            <sp-menu-item disabled>Make Work Path</sp-menu-item>
+        </sp-action-menu>
+    </sp-card>
+</div>
+```
+
+### Gallery
+
+Gallery cards can contain a heading, a subheading, an image preview, a description, and a footer.
+
+```html
+<div style="width: 532px; max-width: 100%; height: 224px">
+    <sp-card variant="gallery" heading="Card Heading" subheading="JPG Photo">
+        <img alt="" slot="preview" src="https://picsum.photos/532/192" />
+        <div slot="description">10/15/18</div>
+        <div slot="footer">Footer</div>
+    </sp-card>
+</div>
+```
+
+### Size
+
+`size="s"` will delivery the `<sp-card>` element at a "small" size. It can be leveraged with a standard card:
+
+```html demo
+<div style="width: 208px; height: 264px">
+    <sp-card size="s" heading="Card Heading" subheading="JPG Photo">
+        <img
+            slot="cover-photo"
+            alt="Demo Image"
+            src="https://picsum.photos/110"
+        />
+        <div slot="footer">Footer</div>
+    </sp-card>
+</div>
+```
+
+A `horizontal` card:
+
+```html demo
+<div style="color: var(--spectrum-neutral-content-color-default);">
+    <sp-card size="s" horizontal heading="Card Heading" subheading="JPG Photo">
+        <sp-icon slot="preview" style="width: 36px; height: 36px;">
+            <svg
+                xmlns="http://www.w3.org/2000/svg"
+                viewBox="0 0 36 36"
+                aria-hidden="true"
+                role="img"
+                fill="currentColor"
+            >
+                <path d="M20 2v10h10L20 2z" />
+                <path
+                    d="M19 14a1 1 0 01-1-1V2H7a1 1 0 00-1 1v30a1 1 0 001 1h22a1 1 0 001-1V14zm7 15.5a.5.5 0 01-.5.5h-15a.5.5 0 01-.5-.5v-1a.5.5 0 01.5-.5h15a.5.5 0 01.5.5zm0-4a.5.5 0 01-.5.5h-15a.5.5 0 01-.5-.5v-1a.5.5 0 01.5-.5h15a.5.5 0 01.5.5zm0-4a.5.5 0 01-.5.5h-15a.5.5 0 01-.5-.5v-1a.5.5 0 01.5-.5h15a.5.5 0 01.5.5z"
+                />
+            </svg>
+        </sp-icon>
+    </sp-card>
+</div>
+```
+
+Or a `quiet` card:
+
+```html demo
+<div
+    style="color: var(--spectrum-neutral-content-color-default); width: 110px;"
+>
+    <sp-card
+        size="s"
+        heading="Card Heading"
+        subheading="JPG Photo"
+        variant="quiet"
+    >
+        <img src="https://picsum.photos/110" alt="Demo Image" slot="preview" />
+        <div slot="footer">Footer</div>
+        <sp-action-menu
+            label="More Actions"
+            slot="actions"
+            placement="bottom-end"
+            quiet
+        >
+            <sp-menu-item>Deselect</sp-menu-item>
+            <sp-menu-item>Select Inverse</sp-menu-item>
+            <sp-menu-item>Feather...</sp-menu-item>
+            <sp-menu-item>Select and Mask...</sp-menu-item>
+            <sp-menu-divider></sp-menu-divider>
+            <sp-menu-item>Save Selection</sp-menu-item>
+            <sp-menu-item disabled>Make Work Path</sp-menu-item>
+        </sp-action-menu>
+    </sp-card>
+</div>
+```

package/package.json

@@ -0,0 +1,78 @@
+{
+    "name": "@spectrum-web-components/card",
+    "version": "0.0.0-20241209155954",
+    "publishConfig": {
+        "access": "public"
+    },
+    "description": "",
+    "license": "Apache-2.0",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/adobe/spectrum-web-components.git",
+        "directory": "packages/card"
+    },
+    "author": "",
+    "homepage": "https://opensource.adobe.com/spectrum-web-components/components/card",
+    "bugs": {
+        "url": "https://github.com/adobe/spectrum-web-components/issues"
+    },
+    "main": "./src/index.js",
+    "module": "./src/index.js",
+    "type": "module",
+    "exports": {
+        ".": {
+            "development": "./src/index.dev.js",
+            "default": "./src/index.js"
+        },
+        "./package.json": "./package.json",
+        "./src/Card.js": {
+            "development": "./src/Card.dev.js",
+            "default": "./src/Card.js"
+        },
+        "./src/card-overrides.css.js": "./src/card-overrides.css.js",
+        "./src/card.css.js": "./src/card.css.js",
+        "./src/index.js": {
+            "development": "./src/index.dev.js",
+            "default": "./src/index.js"
+        },
+        "./sp-card.js": {
+            "development": "./sp-card.dev.js",
+            "default": "./sp-card.js"
+        }
+    },
+    "scripts": {
+        "test": "echo \"Error: run tests from mono-repo root.\" && exit 1"
+    },
+    "files": [
+        "**/*.d.ts",
+        "**/*.js",
+        "**/*.js.map",
+        "custom-elements.json",
+        "!stories/",
+        "!test/"
+    ],
+    "keywords": [
+        "spectrum css",
+        "web components",
+        "lit-element",
+        "lit-html"
+    ],
+    "dependencies": {
+        "@spectrum-web-components/asset": "0.0.0-20241209155954",
+        "@spectrum-web-components/base": "0.0.0-20241209155954",
+        "@spectrum-web-components/checkbox": "0.0.0-20241209155954",
+        "@spectrum-web-components/divider": "0.0.0-20241209155954",
+        "@spectrum-web-components/icons-workflow": "0.0.0-20241209155954",
+        "@spectrum-web-components/shared": "0.0.0-20241209155954",
+        "@spectrum-web-components/styles": "0.0.0-20241209155954"
+    },
+    "devDependencies": {
+        "@spectrum-css/card": "^10.0.0-s2-foundations.20"
+    },
+    "types": "./src/index.d.ts",
+    "customElements": "custom-elements.json",
+    "sideEffects": [
+        "./sp-*.js",
+        "./**/*.dev.js"
+    ]
+}

package/sp-card.d.ts

@@ -0,0 +1,6 @@
+import { Card } from './src/Card.js';
+declare global {
+    interface HTMLElementTagNameMap {
+        'sp-card': Card;
+    }
+}

package/sp-card.dev.js

@@ -0,0 +1,5 @@
+"use strict";
+import { Card } from "./src/Card.dev.js";
+import { defineElement } from "@spectrum-web-components/base/src/define-element.js";
+defineElement("sp-card", Card);
+//# sourceMappingURL=sp-card.dev.js.map

package/sp-card.dev.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["sp-card.ts"],
+  "sourcesContent": ["/*\nCopyright 2020 Adobe. All rights reserved.\nThis file is licensed to you under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License. You may obtain a copy\nof the License at http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software distributed under\nthe License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\nOF ANY KIND, either express or implied. See the License for the specific language\ngoverning permissions and limitations under the License.\n*/\n\nimport { Card } from './src/Card.dev.js'\nimport { defineElement } from '@spectrum-web-components/base/src/define-element.js';\n\ndefineElement('sp-card', Card);\n\ndeclare global {\n    interface HTMLElementTagNameMap {\n        'sp-card': Card;\n    }\n}\n"],
+  "mappings": ";AAYA,SAAS,YAAY;AACrB,SAAS,qBAAqB;AAE9B,cAAc,WAAW,IAAI;",
+  "names": []
+}

package/sp-card.js

@@ -0,0 +1,2 @@
+"use strict";import{Card as e}from"./src/Card.js";import{defineElement as a}from"@spectrum-web-components/base/src/define-element.js";a("sp-card",e);
+//# sourceMappingURL=sp-card.js.map

package/sp-card.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["sp-card.ts"],
+  "sourcesContent": ["/*\nCopyright 2020 Adobe. All rights reserved.\nThis file is licensed to you under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License. You may obtain a copy\nof the License at http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software distributed under\nthe License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\nOF ANY KIND, either express or implied. See the License for the specific language\ngoverning permissions and limitations under the License.\n*/\n\nimport { Card } from './src/Card.js';\nimport { defineElement } from '@spectrum-web-components/base/src/define-element.js';\n\ndefineElement('sp-card', Card);\n\ndeclare global {\n    interface HTMLElementTagNameMap {\n        'sp-card': Card;\n    }\n}\n"],
+  "mappings": "aAYA,OAAS,QAAAA,MAAY,gBACrB,OAAS,iBAAAC,MAAqB,sDAE9BA,EAAc,UAAWD,CAAI",
+  "names": ["Card", "defineElement"]
+}

package/src/Card.d.ts

@@ -0,0 +1,62 @@
+import { CSSResultArray, PropertyValues, SpectrumElement, TemplateResult } from '@spectrum-web-components/base';
+import '@spectrum-web-components/asset/sp-asset.js';
+import '@spectrum-web-components/checkbox/sp-checkbox.js';
+import '@spectrum-web-components/popover/sp-popover.js';
+import '@spectrum-web-components/divider/sp-divider.js';
+declare const Card_base: typeof SpectrumElement & {
+    new (...args: any[]): import("@spectrum-web-components/shared/src/observe-slot-presence.js").SlotPresenceObservingInterface;
+    prototype: import("@spectrum-web-components/shared/src/observe-slot-presence.js").SlotPresenceObservingInterface;
+} & {
+    new (...args: any[]): import("@spectrum-web-components/base").SizedElementInterface;
+    prototype: import("@spectrum-web-components/base").SizedElementInterface;
+} & {
+    new (...args: any[]): import("@spectrum-web-components/shared/src/like-anchor.js").LikeAnchorInterface;
+    prototype: import("@spectrum-web-components/shared/src/like-anchor.js").LikeAnchorInterface;
+};
+/**
+ * @element sp-card
+ *
+ * @fires change - Announces a change in the `selected` property of a card
+ * @slot preview - This is the preview image for Gallery Cards
+ * @slot cover-photo - This is the cover photo for Default and Quiet Cards
+ * @slot heading - HTML content to be listed as the heading
+ * @slot subheading - HTML content to be listed as the subheading
+ * @slot description - A description of the card
+ * @slot actions - an `sp-action-menu` element outlining actions to take on the represened object
+ * @slot footer - Footer text
+ */
+export declare class Card extends Card_base {
+    static get styles(): CSSResultArray;
+    asset?: 'file' | 'folder';
+    variant: 'standard' | 'gallery' | 'quiet';
+    get selected(): boolean;
+    set selected(selected: boolean);
+    private _selected;
+    heading: string;
+    horizontal: boolean;
+    private likeAnchor?;
+    focused: boolean;
+    toggles: boolean;
+    value: string;
+    subheading: string;
+    protected get hasCoverPhoto(): boolean;
+    protected get hasPreview(): boolean;
+    click(): void;
+    private handleFocusin;
+    private handleFocusout;
+    private handleKeydown;
+    private handleSelectedChange;
+    toggleSelected(): void;
+    private announceChange;
+    private stopPropagationOnHref;
+    private handlePointerdown;
+    protected get renderHeading(): TemplateResult;
+    protected get renderPreviewImage(): TemplateResult;
+    protected get renderCoverImage(): TemplateResult;
+    protected get images(): TemplateResult[];
+    private renderImage;
+    private get renderSubtitleAndDescription();
+    protected render(): TemplateResult;
+    protected firstUpdated(changes: PropertyValues): void;
+}
+export {};