@mosaicajs/components 0.2.0 → 0.4.0

package/dist/item-card.d.ts

@@ -9,14 +9,25 @@ import { MosaicaElement, type PickOutcome } from './base.js';
  *
  * The headline is the `title-field` field, or the item's `mosaica_id` when that field is unset or
  * empty. To render a field your own way, as a link for example, put an element in its
- * `field-<name>` slot.
+ * `field-<name>` slot. The card is headed "Item" for a screen reader, with the headline a heading
+ * under it.
+ *
+ * A value over 60 characters is kept to six lines, with a Show more button under it where that
+ * cuts it short. A `compact` card also keeps its headline to three lines and its subtitle to two,
+ * and its Show all button shows every field and all of each.
+ *
+ * A field named in `image-fields` whose value is an `http:` or `https:` address, or a path
+ * resolved against the page, is drawn as the image at that address, across the card's width. The viewer's browser loads it from the host
+ * that serves it, without a referrer. Its alternative text is the item's `title-field` value, or
+ * the field's name where the item has none. A value that is not such an address, and an image that
+ * does not load, are shown as text.
  *
  * The Open button appears only when you set `open-url` or `open`. `open-url` is a link template
  * such as `https://www.geonames.org/{geonameid}`, in which each `{name}` is replaced by the item's
  * value for that field. Because the values are URL-encoded, a template cannot open an address that
  * a field already holds, so set `open` to a function for that. An item gets no Open button when it
- * has no value for a field the template names. A function in `open` is called with the item's
- * `mosaica_id` and fields, and it takes precedence over `open-url`.
+ * has no value for a field the template names. The link opens in a new tab. A function in `open`
+ * is called with the item's `mosaica_id` and fields, and it takes precedence over `open-url`.
  *
  * @summary A card showing an item's fields, with an optional Open button.
  * @tagname mosaica-item-card
@@ -31,22 +42,26 @@ import { MosaicaElement, type PickOutcome } from './base.js';
  * @csspart title - The header row: the headline or the state, and the close button.
  * @csspart close - The close button.
  * @csspart state - The state line, with `data-state`: `shown`, `empty` (no item, or a click that
- *   found nothing), `refused` or `detached`.
+ *   found nothing), `refused` or `detached`. It is inside a `role="status"` region.
  * @csspart refusal - The words "Item unavailable", with `data-code` set to the refusal's code if
  *   the server refused the record. For a broken pick, the details are in the map's `lastPick`.
  * @csspart reason - The server's reason for refusing the record, under "Item unavailable".
- * @csspart headline - The headline, with `data-name` set to the field it shows.
+ * @csspart headline - The headline, an `<h3>`, with `data-name` set to the field it shows.
  * @csspart subtitle - The `subtitle-field` value under the headline, when `compact` is set.
  * @csspart show-all - The "Show all N fields" button, when `compact` is set, with `aria-expanded`.
- * @csspart view-chip - One view the item is in, with `data-view` and `aria-current` on the current
- *   view.
+ *   It reads "Show all" where every field is shown and only text is cut short.
+ * @csspart view-chip - One view the item is in, with `data-view`, and `aria-current` and a bar
+ *   under the current view.
  * @csspart field - One field, with `data-name`, and `data-prose` on a value over 60 characters.
- * @csspart label - A field's name, and the heading above the view chips.
- * @csspart value - A field's value.
+ * @csspart label - A field's name, a `<dt>`, and the heading above the view chips.
+ * @csspart value - A field's value, a `<dd>`.
+ * @csspart more - The Show more button under a long value that is cut short, with `aria-expanded`.
+ * @csspart image - A field's value drawn as an image, under `image-fields`.
  * @csspart scoped - The group-scoped values, grouped by key.
  * @csspart key - One key's heading among the group-scoped values, with `data-key`.
  * @csspart open - The Open button.
- * @csspart copy - The Copy id button, which copies the `mosaica_id` to the clipboard.
+ * @csspart copy - The Copy id button, which copies the `mosaica_id` to the clipboard and says to a
+ *   screen reader whether it did.
  */
 export declare class MosaicaItemCard extends MosaicaElement {
     static styles: import("lit").CSSResult[];
@@ -75,6 +90,11 @@ export declare class MosaicaItemCard extends MosaicaElement {
      * Unset, the first three. The full list shows these fields first, then the rest.
      */
     accessor cardFields: string;
+    /**
+     * The fields whose value is the address of an image, separated by spaces or commas. Each is drawn
+     * as its image rather than as text.
+     */
+    accessor imageFields: string;
     /**
      * The link template for Open, with `{name}` for the value of the field `name` and `{mosaica_id}`
      * for the item's id. Without it or `open`, there is no Open button.
@@ -85,6 +105,17 @@ export declare class MosaicaItemCard extends MosaicaElement {
     /** Whether "Show all" was pressed, for the item it was pressed on. @internal */
     accessor expanded: boolean;
     private expandedFor;
+    /** The long values shown whole on the full card, by field, for the item shown. @internal */
+    accessor opened: ReadonlySet<string>;
+    /** The fields whose headline, subtitle or value is cut short where it is drawn. @internal */
+    accessor clipped: ReadonlySet<string>;
+    /** What the last press of Copy id came to, for the item shown. @internal */
+    accessor copied: string;
+    private resized;
+    /** The image addresses that failed to load, shown as text. @internal */
+    accessor broken: ReadonlySet<string>;
+    /** `image-fields` as a list, kept in step by `willUpdate`. */
+    private imageNames;
     /** A category value's title as the store holds it, else from the legend or a suggestion page, else its key. */
     private titleOf;
     /** A field's value as text: a category value by its title, anything else by its declared type. */
@@ -94,17 +125,30 @@ export declare class MosaicaItemCard extends MosaicaElement {
      * set before the render, so the render changes nothing it reads.
      */
     protected willUpdate(changed: PropertyValues<this>): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changed: PropertyValues<this>): void;
+    /**
+     * Note which clamped texts are cut short at the card's width, so each is offered whole. A text
+     * shown whole keeps what was noted while it was clamped, so the button that shows it stays.
+     */
+    private measure;
+    /** Copy the id to the clipboard and say in the status region how that went. */
+    private copy;
     private get shown();
     render(): TemplateResult | typeof nothing;
-    /** The card under `compact`: headline and subtitle, three fields, and Show all beside Open. */
-    private compactBody;
+    /** An item's headline, for the header row, and what the card shows under it: the full card's, or under `compact` the shorter one's. */
+    private card;
     /**
      * Open, where the host says what it does: a button that calls `open`, else a link to `open-url`
-     * filled from the item, else nothing. Each fires `mosaica-open`.
+     * filled from the item, which opens in a new tab and says so to a screen reader, else nothing.
+     * Each fires `mosaica-open`. `mark` is drawn before the word.
      */
     private openButton;
     /** The fields of `fields` that `card-fields` names, in its order. */
     private named;
+    /** The address of the image a field's value names, where `image-fields` lists the field. */
+    private imageOf;
     /** `fields` with those `card-fields` names first, in its order. */
     private namedFirst;
     /**
@@ -124,7 +168,11 @@ export declare class MosaicaItemCard extends MosaicaElement {
      * key through a `members` group share a heading.
      */
     private scoped;
-    /** One field, presented by its declared type; prose spans the grid. */
+    /**
+     * One field, presented by its declared type; prose and images span the grid. An image's
+     * alternative text is the item's `headline` where it has one, since its caption is the label
+     * above it. On the full card, prose a clamp cuts short has a button that shows it whole.
+     */
     private field;
 }
 declare global {