@internetarchive/elements 0.2.14-webdev-8969.0 → 0.2.14-webdev-9022.0

package/README.md

@@ -143,6 +143,26 @@ src
 ```
 Export your component in `src/index.ts`
 
+### Naming
+Custom elements all share one global registry, and that registry is shared with every other script on the host page. Give each element a name specific enough that nothing else would plausibly want it.
+
+If a component is built from several elements, prefix its parts with the component's own name rather than naming them generically, and keep the file name matching the tag:
+```
+src
+- elements
+  - ia-foobar
+    - ia-foobar.ts // ia-foobar
+    - ia-foobar-list-item.ts // ia-foobar-list-item, not ia-list-item
+```
+Declare each element in `HTMLElementTagNameMap` so `querySelector` is typed and a mistyped tag in a template is caught at build time:
+```ts
+declare global {
+  interface HTMLElementTagNameMap {
+    'ia-foobar-list-item': IAFoobarListItem;
+  }
+}
+```
+
 ### Story
 To demo your component, we have a component catalog that you can add your demo to. Create a component in your component directory. Name it `COMPONENT-NAME-story.ts`, ie `ia-button-story.ts`.
 

package/dist/src/elements/ia-image-viewer/ia-image-viewer.d.ts

@@ -0,0 +1,147 @@
+import { type CSSResultGroup, LitElement, nothing, type PropertyValues, type TemplateResult } from 'lit';
+import type { ImageViewerImage, SlideDirection } from './models.js';
+import './ia-imgview-slide.js';
+import './ia-imgview-controls.js';
+/**
+ * A swipeable image carousel.
+ *
+ * Shows one image at a time from a list, with previous/next buttons, a
+ * counter, keyboard arrows, horizontal wheel scrolling and touch swipes.
+ * Clicking an image opens it in a new tab.
+ *
+ * The viewer holds no opinion about where the images came from: it takes a
+ * plain list of names and URLs, and reports the image it lands on through
+ * `imageChanged` so a host can mirror that into its own URL or analytics.
+ *
+ * @fires imageChanged - The viewer settled on a new image.
+ * @fires imageLoaded - An image the viewer showed finished loading.
+ * @fires imageLoadFailed - An image the viewer showed could not be loaded.
+ *   Fires once per image until it loads successfully or the set changes.
+ * @fires imageActivated - An image was clicked. Cancelable: preventing it
+ *   stops the default of opening the image in a new tab.
+ */
+export declare class IAImageViewer extends LitElement {
+    images: ImageViewerImage[];
+    /**
+     * Name of the image to show. Changing it jumps straight to that image
+     * without animating. An unknown name shows the first image.
+     */
+    currentImageName?: string;
+    /** Read by the gesture controller, which tracks touches against it. */
+    imageArea?: HTMLElement;
+    /** Read by the gesture controller, which translates it during a drag. */
+    slideTrack?: HTMLElement;
+    /** Read by the gesture controller to navigate relative to the current image. */
+    currentIndex: number;
+    private animating;
+    /**
+     * Incremented when an animation is interrupted to force the track element to
+     * be recreated via the `keyed()` directive, which guarantees the CSS
+     * animation restarts even if the direction is the same.
+     */
+    private slideGeneration;
+    /** Which edge just wrapped, if any. Drives the glow indicator. */
+    private wrapEdge;
+    /**
+     * Images already reported as failed, so a broken image isn't counted again
+     * every time the viewer passes over it. Navigating back re-fires `error` on
+     * the recreated element, and the neighbouring slides staged during an
+     * animation or a drag load the same image too, so without this a single
+     * broken derivative reports several times a session.
+     *
+     * Cleared when the image set changes, which is the point a name stops
+     * standing for the same file.
+     */
+    private reportedFailures;
+    private slideTarget;
+    private slideDirection;
+    private gestures;
+    get imageCount(): number;
+    /** The image currently on screen, if there is one. */
+    get currentImage(): ImageViewerImage | undefined;
+    protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Where to land when the images or the requested name change.
+     *
+     * A new `currentImageName` is the host asking for a particular image, so it
+     * wins. A new `images` array on its own isn't: a host that builds its list
+     * in a getter hands over a fresh array on every render, which says nothing
+     * about the images having changed. So the viewer holds its place by name and
+     * only goes back to the start when the image it was showing is really gone.
+     */
+    private indexToShow;
+    render(): TemplateResult | typeof nothing;
+    private slideTemplate;
+    /**
+     * Announces the image to a screen reader, which otherwise gets nothing when
+     * the counter and the picture change under it.
+     */
+    private get announcementTemplate();
+    /**
+     * Passes a slide's load result on to the host, which is where reporting
+     * belongs. The slide's own events stop at this shadow root, so they're
+     * re-dispatched rather than allowed to escape.
+     */
+    private onImageLoaded;
+    private onImageFailed;
+    /**
+     * Decides whether a click on a slide opens the image.
+     *
+     * Two things can stop it: the click is the tail end of a swipe, or the host
+     * cancels the event to show the image its own way. The slide's event doesn't
+     * cross this shadow root, so it's re-raised here for the host to see, and a
+     * veto is passed back down to cancel the click.
+     */
+    private onImageActivated;
+    /**
+     * Inserts the neighbouring slides around the current one so the touch target
+     * element stays in the DOM (avoiding touchcancel). These aren't rendered
+     * from the template, so they're marked for the gesture controller to clean
+     * up. The dragging class shifts the track to centre on the middle slide.
+     */
+    insertDragSlides(): void;
+    removeDragSlides(): void;
+    private createDragSlide;
+    showNext(): void;
+    showPrevious(): void;
+    /**
+     * Starts the move to another image. With reduced motion there's no animation
+     * to wait on, so the move lands immediately: nothing would fire the
+     * `animationend` that otherwise commits it.
+     */
+    private moveTo;
+    /**
+     * Moves to the image a completed drag landed on. The drag has already
+     * animated the track there, so this only updates state.
+     */
+    commitDrag(direction: SlideDirection): void;
+    /**
+     * If an animation is in progress, immediately commit its target so the next
+     * animation starts from the right position. Bumps the generation key to
+     * force the track element to be recreated, which restarts the CSS animation.
+     */
+    settleIfAnimating(): void;
+    private onWrapGlowEnd;
+    private onSlideEnd;
+    /** Finishes a move, however it was driven. */
+    private settleAtCurrentIndex;
+    private emitImageChanged;
+    /**
+     * Preloads the next and previous images around `currentIndex` so the first
+     * navigation feels instant.
+     */
+    private preloadAdjacentImages;
+    /**
+     * Preloads images adjacent to the given index. Called both at rest (around
+     * `currentIndex`) and at the start of a move (around the target) so rapid
+     * navigation stays ahead of the browser cache.
+     *
+     * A preload that fails is deliberately not reported. These requests are
+     * speculative and the viewer may never show them, so counting them would
+     * inflate the failure rate with images nobody looked at. Navigating to a
+     * broken image renders a real slide, whose `error` reports it then.
+     */
+    preloadAroundIndex(index: number): void;
+    static get styles(): CSSResultGroup;
+}
+//# sourceMappingURL=ia-image-viewer.d.ts.map

package/dist/src/elements/ia-image-viewer/ia-image-viewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ia-image-viewer.d.ts","sourceRoot":"","sources":["../../../../src/elements/ia-image-viewer/ia-image-viewer.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EAEnB,UAAU,EACV,OAAO,EACP,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,KAAK,CAAC;AASb,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAY,MAAM,UAAU,CAAC;AAE3E,OAAO,oBAAoB,CAAC;AAC5B,OAAO,uBAAuB,CAAC;AAK/B;;;;;;;;;;;;;;;;;GAiBG;AACH,qBACa,aAAc,SAAQ,UAAU;IAChB,MAAM,EAAE,gBAAgB,EAAE,CAAM;IAE3D;;;OAGG;IACyB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAEtD,uEAAuE;IACjD,SAAS,CAAC,EAAE,WAAW,CAAC;IAE9C,yEAAyE;IAClD,UAAU,CAAC,EAAE,WAAW,CAAC;IAEhD,gFAAgF;IACvE,YAAY,SAAK;IAEjB,OAAO,CAAC,SAAS,CAAS;IAEnC;;;;OAIG;IACM,OAAO,CAAC,eAAe,CAAK;IAErC,kEAAkE;IACzD,OAAO,CAAC,QAAQ,CAAyB;IAElD;;;;;;;;;OASG;IACH,OAAO,CAAC,gBAAgB,CAAqB;IAE7C,OAAO,CAAC,WAAW,CAAuB;IAE1C,OAAO,CAAC,cAAc,CAA+B;IAErD,OAAO,CAAC,QAAQ,CAAiC;IAEjD,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,sDAAsD;IACtD,IAAI,YAAY,IAAI,gBAAgB,GAAG,SAAS,CAE/C;IAED,SAAS,CAAC,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAenD;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;IAyBnB,MAAM,IAAI,cAAc,GAAG,OAAO,OAAO;IA6EzC,OAAO,CAAC,aAAa;IAIrB;;;OAGG;IACH,OAAO,KAAK,oBAAoB,GAW/B;IAED;;;;OAIG;IACH,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,aAAa;IASrB;;;;;;;OAOG;IACH,OAAO,CAAC,gBAAgB;IAcxB;;;;;OAKG;IACH,gBAAgB,IAAI,IAAI;IAgBxB,gBAAgB,IAAI,IAAI;IAOxB,OAAO,CAAC,eAAe;IASvB,QAAQ,IAAI,IAAI;IAKhB,YAAY,IAAI,IAAI;IAQpB;;;;OAIG;IACH,OAAO,CAAC,MAAM;IAmBd;;;OAGG;IACH,UAAU,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI;IAc3C;;;;OAIG;IACH,iBAAiB,IAAI,IAAI;IAMzB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,UAAU;IAMlB,8CAA8C;IAC9C,OAAO,CAAC,oBAAoB;IAS5B,OAAO,CAAC,gBAAgB;IAUxB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAI7B;;;;;;;;;OASG;IACH,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAUvC,MAAM,KAAK,MAAM,IAAI,cAAc,CAgJlC;CACF"}