@internetarchive/collection-browser 4.4.1 → 4.5.1-alpha-webdev8221.0

package/package.json

@@ -1,120 +1,120 @@
-{
-  "name": "@internetarchive/collection-browser",
-  "description": "The Internet Archive Collection Browser.",
-  "license": "AGPL-3.0-only",
-  "author": "Internet Archive",
-  "version": "4.4.1",
-  "main": "dist/index.js",
-  "module": "dist/index.js",
-  "scripts": {
-    "start": "vite",
-    "prepare:ghpages": "rimraf ghpages && yarn run prepare && vite build",
-    "prepare": "rimraf dist && tsc && husky install",
-    "lint": "eslint . && prettier \"**/*.ts\" --check",
-    "format": "eslint . --fix && prettier \"**/*.ts\" --write",
-    "circular": "madge --circular --extensions ts .",
-    "test": "tsc && yarn run lint && yarn run circular && wtr --coverage",
-    "test:fast": "tsc && wtr --coverage",
-    "test:watch": "tsc && concurrently -k -r \"tsc --watch --preserveWatchOutput\" \"wtr --watch\"",
-    "deploy": "yarn run deploy:run -e $(git branch --show-current)",
-    "deploy:run": "yarn run prepare:ghpages && touch ghpages/.nojekyll && yarn run deploy:gh",
-    "deploy:gh": "gh-pages -t -d ghpages -m \"Build for $(git log --pretty=format:\"%h %an %ai %s\" -n1) [skip ci]\"",
-    "typecheck": "yarn tsc --noEmit"
-  },
-  "types": "dist/index.d.ts",
-  "dependencies": {
-    "@a11y/focus-trap": "^1.0.5",
-    "@internetarchive/analytics-manager": "^0.1.4",
-    "@internetarchive/elements": "^0.2.2",
-    "@internetarchive/feature-feedback": "^1.0.0",
-    "@internetarchive/field-parsers": "^1.0.0",
-    "@internetarchive/histogram-date-range": "^1.4.2",
-    "@internetarchive/ia-dropdown": "^2.0.0",
-    "@internetarchive/iaux-item-metadata": "^1.0.5",
-    "@internetarchive/infinite-scroller": "^2.0.0",
-    "@internetarchive/modal-manager": "^2.0.5",
-    "@internetarchive/search-service": "2.7.2",
-    "@internetarchive/shared-resize-observer": "^0.2.0",
-    "@lit/localize": "^0.12.2",
-    "dompurify": "^3.2.4",
-    "lit": "^2.8.0 || ^3.3.2",
-    "typescript-cookie": "^1.0.6"
-  },
-  "devDependencies": {
-    "@internetarchive/result-type": "^0.0.1",
-    "@open-wc/eslint-config": "^13.0.0",
-    "@open-wc/testing": "^4.0.0",
-    "@rollup/plugin-image": "^3.0.3",
-    "@types/dompurify": "^3.2.0",
-    "@types/mocha": "^10.0.10",
-    "@typescript-eslint/eslint-plugin": "^8.27.0",
-    "@typescript-eslint/parser": "^8.27.0",
-    "@vitejs/plugin-basic-ssl": "^2.1.4",
-    "@web/dev-server": "^0.4.6",
-    "@web/dev-server-rollup": "^0.6.4",
-    "@web/test-runner": "^0.20.0",
-    "concurrently": "^9.1.2",
-    "eslint": "^9.22.0",
-    "eslint-config-prettier": "^10.1.1",
-    "eslint-plugin-html": "^8.1.2",
-    "eslint-plugin-import": "^2.31.0",
-    "eslint-plugin-lit": "^2.0.0",
-    "eslint-plugin-lit-a11y": "^5.0.0",
-    "eslint-plugin-no-only-tests": "^3.3.0",
-    "eslint-plugin-wc": "^3.0.0",
-    "gh-pages": "^6.3.0",
-    "husky": "^9.1.7",
-    "madge": "^8.0.0",
-    "prettier": "^3.5.3",
-    "rimraf": "^6.0.1",
-    "sinon": "^19.0.4",
-    "tslib": "^2.8.1",
-    "typescript": "^5.8.2",
-    "vite": "^8.0.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "eslintConfig": {
-    "parser": "@typescript-eslint/parser",
-    "extends": [
-      "@open-wc",
-      "prettier"
-    ],
-    "plugins": [
-      "@typescript-eslint"
-    ],
-    "rules": {
-      "no-unused-vars": "off",
-      "@typescript-eslint/no-unused-vars": [
-        "error"
-      ],
-      "no-shadow": "off",
-      "@typescript-eslint/no-shadow": [
-        "error"
-      ],
-      "class-methods-use-this": "off",
-      "import/no-unresolved": "off",
-      "import/extensions": [
-        "off",
-        "ignorePackages",
-        {
-          "js": "never",
-          "ts": "never"
-        }
-      ],
-      "no-unsafe-optional-chaining": "warn",
-      "default-param-last": "warn"
-    }
-  },
-  "prettier": {
-    "singleQuote": true,
-    "arrowParens": "avoid"
-  },
-  "lint-staged": {
-    "*.ts": [
-      "eslint --fix",
-      "prettier --write"
-    ]
-  }
-}
+{
+  "name": "@internetarchive/collection-browser",
+  "description": "The Internet Archive Collection Browser.",
+  "license": "AGPL-3.0-only",
+  "author": "Internet Archive",
+  "version": "4.5.1-alpha-webdev8221.0",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "scripts": {
+    "start": "vite",
+    "prepare:ghpages": "rimraf ghpages && yarn run prepare && vite build",
+    "prepare": "rimraf dist && tsc && husky install",
+    "lint": "eslint . && prettier \"**/*.ts\" --check",
+    "format": "eslint . --fix && prettier \"**/*.ts\" --write",
+    "circular": "madge --circular --extensions ts .",
+    "test": "tsc && yarn run lint && yarn run circular && wtr --coverage",
+    "test:fast": "tsc && wtr --coverage",
+    "test:watch": "tsc && concurrently -k -r \"tsc --watch --preserveWatchOutput\" \"wtr --watch\"",
+    "deploy": "yarn run deploy:run -e $(git branch --show-current)",
+    "deploy:run": "yarn run prepare:ghpages && touch ghpages/.nojekyll && yarn run deploy:gh",
+    "deploy:gh": "gh-pages -t -d ghpages -m \"Build for $(git log --pretty=format:\"%h %an %ai %s\" -n1) [skip ci]\"",
+    "typecheck": "yarn tsc --noEmit"
+  },
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@a11y/focus-trap": "^1.0.5",
+    "@internetarchive/analytics-manager": "^0.1.4",
+    "@internetarchive/elements": "^0.2.2",
+    "@internetarchive/feature-feedback": "^1.0.0",
+    "@internetarchive/field-parsers": "^1.0.0",
+    "@internetarchive/histogram-date-range": "^1.4.2",
+    "@internetarchive/ia-dropdown": "^2.0.0",
+    "@internetarchive/iaux-item-metadata": "^1.0.5",
+    "@internetarchive/infinite-scroller": "^2.0.0",
+    "@internetarchive/modal-manager": "^2.0.5",
+    "@internetarchive/search-service": "^2.7.2",
+    "@internetarchive/shared-resize-observer": "^0.2.0",
+    "@lit/localize": "^0.12.2",
+    "dompurify": "^3.2.4",
+    "lit": "^2.8.0 || ^3.3.2",
+    "typescript-cookie": "^1.0.6"
+  },
+  "devDependencies": {
+    "@internetarchive/result-type": "^0.0.1",
+    "@open-wc/eslint-config": "^13.0.0",
+    "@open-wc/testing": "^4.0.0",
+    "@rollup/plugin-image": "^3.0.3",
+    "@types/dompurify": "^3.2.0",
+    "@types/mocha": "^10.0.10",
+    "@typescript-eslint/eslint-plugin": "^8.27.0",
+    "@typescript-eslint/parser": "^8.27.0",
+    "@vitejs/plugin-basic-ssl": "^2.1.4",
+    "@web/dev-server": "^0.4.6",
+    "@web/dev-server-rollup": "^0.6.4",
+    "@web/test-runner": "^0.20.0",
+    "concurrently": "^9.1.2",
+    "eslint": "^9.22.0",
+    "eslint-config-prettier": "^10.1.1",
+    "eslint-plugin-html": "^8.1.2",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-lit": "^2.0.0",
+    "eslint-plugin-lit-a11y": "^5.0.0",
+    "eslint-plugin-no-only-tests": "^3.3.0",
+    "eslint-plugin-wc": "^3.0.0",
+    "gh-pages": "^6.3.0",
+    "husky": "^9.1.7",
+    "madge": "^8.0.0",
+    "prettier": "^3.5.3",
+    "rimraf": "^6.0.1",
+    "sinon": "^19.0.4",
+    "tslib": "^2.8.1",
+    "typescript": "^5.8.2",
+    "vite": "^8.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "eslintConfig": {
+    "parser": "@typescript-eslint/parser",
+    "extends": [
+      "@open-wc",
+      "prettier"
+    ],
+    "plugins": [
+      "@typescript-eslint"
+    ],
+    "rules": {
+      "no-unused-vars": "off",
+      "@typescript-eslint/no-unused-vars": [
+        "error"
+      ],
+      "no-shadow": "off",
+      "@typescript-eslint/no-shadow": [
+        "error"
+      ],
+      "class-methods-use-this": "off",
+      "import/no-unresolved": "off",
+      "import/extensions": [
+        "off",
+        "ignorePackages",
+        {
+          "js": "never",
+          "ts": "never"
+        }
+      ],
+      "no-unsafe-optional-chaining": "warn",
+      "default-param-last": "warn"
+    }
+  },
+  "prettier": {
+    "singleQuote": true,
+    "arrowParens": "avoid"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  }
+}

package/renovate.json

@@ -1,6 +1,6 @@
-{
-  "extends": [
-    "config:base",
-    ":preserveSemverRanges"
-  ]
-}
+{
+  "extends": [
+    "config:base",
+    ":preserveSemverRanges"
+  ]
+}

package/src/app-root.ts

@@ -384,6 +384,16 @@ export class AppRoot extends LitElement {
               />
               <label for="enable-smart-facet-bar">Enable smart facet bar</label>
             </div>
+            <div class="checkbox-control">
+              <input
+                type="checkbox"
+                id="enable-tile-actions"
+                @click=${this.tileActionsCheckboxChanged}
+              />
+              <label for="enable-tile-actions"
+                >Enable tile action buttons</label
+              >
+            </div>
           </fieldset>
 
           <fieldset class="cb-visual-appearance">
@@ -584,6 +594,7 @@ export class AppRoot extends LitElement {
           @manageModeChanged=${this.manageModeChanged}
           @itemRemovalRequested=${this.handleItemRemovalRequest}
           @itemManagerRequested=${this.handleItemManagerRequest}
+          @tileActionClicked=${this.handleTileActionClicked}
         >
           ${this.toggleSlots
             ? html`<div slot="sortbar-left-slot">Sort Slot</div>`
@@ -805,6 +816,25 @@ export class AppRoot extends LitElement {
     this.collectionBrowser.showSmartFacetBar = target.checked;
   }
 
+  /**
+   * Handler for when the dev panel's "Enable tile action buttons" checkbox is changed.
+   */
+  private tileActionsCheckboxChanged(e: Event) {
+    const target = e.target as HTMLInputElement;
+    this.collectionBrowser.tileActions = target.checked
+      ? [{ id: 'demo-action', label: 'Return' }]
+      : [];
+  }
+
+  /**
+   * Handler for tile action button clicks (logs to console for QA).
+   */
+  private handleTileActionClicked(
+    e: CustomEvent<{ actionId: string; model: unknown }>,
+  ) {
+    console.log('Tile action clicked:', e.detail.actionId, e.detail.model);
+  }
+
   /**
    * Handler for when the dev panel's "Show facet top slot" checkbox is changed.
    */

package/src/collection-browser.ts

@@ -78,6 +78,7 @@ import { sha1 } from './utils/sha1';
 import type { PlaceholderType } from './empty-placeholder';
 import type { ManageBar } from './manage/manage-bar';
 import type { SmartFacetBar } from './collection-facets/smart-facets/smart-facet-bar';
+import type { LayoutType, TileAction } from './tiles/models';
 
 import '@internetarchive/elements/ia-combo-box/ia-combo-box';
 import './empty-placeholder';
@@ -297,6 +298,15 @@ export class CollectionBrowser
    */
   @property({ type: Boolean }) isManageView = false;
 
+  /** Action buttons to display on each tile */
+  @property({ type: Array }) tileActions: TileAction[] = [];
+
+  /**
+   * The simplified layout to apply to grid-mode tiles, if any. See
+   * `LayoutType` for available options. Has no effect on list display modes.
+   */
+  @property({ type: String }) tileLayoutType: LayoutType = 'default';
+
   @property({ type: String }) manageViewLabel = 'Select items to remove';
 
   /** Whether to replace the default sort options with a slot for customization (default: false) */
@@ -1652,6 +1662,7 @@ export class CollectionBrowser
           .mobileBreakpoint=${this.mobileBreakpoint}
           .loggedIn=${this.loggedIn}
           .suppressBlurring=${this.shouldSuppressTileBlurring}
+          .tileActions=${this.tileActions}
         >
         </tile-dispatcher>
       </div>
@@ -1673,21 +1684,10 @@ export class CollectionBrowser
     this.analyticsHandler?.sendEvent({
       category: this.searchContext,
       action: analyticsActions.histogramChanged,
-      label: this.dateRangeQueryClause,
+      label: this.dataSource.dateRangeQueryClause,
     });
   }
 
-  /**
-   * The Lucene query corresponding to the current date range.
-   */
-  private get dateRangeQueryClause() {
-    if (!this.minSelectedDate || !this.maxSelectedDate) {
-      return undefined;
-    }
-
-    return `year:[${this.minSelectedDate} TO ${this.maxSelectedDate}]`;
-  }
-
   /**
    * Emits an event indicating a change in whether the manage mode is shown.
    */
@@ -1801,7 +1801,9 @@ export class CollectionBrowser
       changed.has('displayMode') ||
       changed.has('baseNavigationUrl') ||
       changed.has('baseImageUrl') ||
-      changed.has('loggedIn')
+      changed.has('loggedIn') ||
+      changed.has('tileActions') ||
+      changed.has('tileLayoutType')
     ) {
       this.infiniteScroller?.reload();
     }
@@ -2635,6 +2637,8 @@ export class CollectionBrowser
         .loggedIn=${this.loggedIn}
         .suppressBlurring=${this.shouldSuppressTileBlurring}
         .isManageView=${this.isManageView}
+        .tileActions=${this.tileActions}
+        .layoutType=${this.tileLayoutType}
         ?showTvClips=${isTVSearch || isTVCollection}
         ?enableHoverPane=${true}
         ?useLocalTime=${shouldUseLocalTime}

package/src/collection-facets/facet-row.ts

@@ -30,6 +30,13 @@ export class FacetRow extends LitElement {
   /** The facet bucket containing details about the state, count, and key for this row */
   @property({ type: Object }) bucket?: FacetBucket;
 
+  /**
+   * Whether to omit the negative/hide button from this facet row if possible.
+   * Has no effect if the facet bucket is itself hidden, in which case the hide
+   * button *must* be shown to represent the state accurately.
+   */
+  @property({ type: Boolean, reflect: true }) omitHideButton = false;
+
   /** The collection name cache for converting collection identifiers to titles */
   @property({ type: Object })
   collectionTitles?: CollectionTitles;
@@ -102,7 +109,10 @@ export class FacetRow extends LitElement {
             id=${showOnlyCheckboxId}
             data-testid=${showOnlyCheckboxId}
           />
-          <div class="hide-facet-container">
+          <div
+            class="hide-facet-container"
+            ?hidden=${this.omitHideButton && !facetHidden}
+          >
             <input
               type="checkbox"
               id=${negativeCheckboxId}

package/src/collection-facets/facets-template.ts

@@ -36,6 +36,7 @@ export class FacetsTemplate extends LitElement {
     if (!facetGroup) return nothing;
 
     const facetBuckets = facetGroup.buckets as FacetBucket[];
+    const isLoneBucket = facetBuckets.length === 1;
 
     // Added data-testid for Playwright testing
     // Using className and aria-labels is not ideal for Playwright locator
@@ -49,6 +50,7 @@ export class FacetsTemplate extends LitElement {
               .facetType=${facetGroup.key}
               .bucket=${bucket}
               .collectionTitles=${this.collectionTitles}
+              ?omitHideButton=${isLoneBucket}
               @facetClick=${this.facetClicked}
             ></facet-row>`,
         )}

package/src/data-source/collection-browser-data-source-interface.ts

@@ -71,6 +71,12 @@ export interface CollectionBrowserDataSourceInterface
    */
   readonly pageSpecifierParams: PageSpecifierParams | null;
 
+  /**
+   * The Lucene query clause corresponding to the current date range,
+   * e.g. `year:[2000 TO 2020]` or `date:[2020-01 TO 2020-12]`.
+   */
+  readonly dateRangeQueryClause: string | undefined;
+
   /**
    * A FilterMap object representing all filters applied to the current search,
    * including any facets, letter filters, and date ranges.

package/src/data-source/collection-browser-data-source.ts

@@ -33,6 +33,7 @@ import type { CollectionBrowserDataSourceInterface } from './collection-browser-
 import type { CollectionBrowserSearchInterface } from './collection-browser-query-state';
 import { sha1 } from '../utils/sha1';
 import { mergeSelectedFacets } from '../utils/facet-utils';
+import { dateFilterField } from '../utils/date-filter-field';
 
 export class CollectionBrowserDataSource
   implements CollectionBrowserDataSourceInterface
@@ -746,7 +747,10 @@ export class CollectionBrowserDataSource
       selectedCreatorFilter,
     } = this.host;
 
-    const dateField = this.host.searchType === SearchType.TV ? 'date' : 'year';
+    const dateField = dateFilterField(
+      this.host.minSelectedDate,
+      this.host.maxSelectedDate,
+    );
 
     if (minSelectedDate) {
       builder.addFilter(
@@ -901,12 +905,16 @@ export class CollectionBrowserDataSource
     return this.joinFacetClauses(facetClauses)?.trim();
   }
 
-  private get dateRangeQueryClause(): string | undefined {
+  get dateRangeQueryClause(): string | undefined {
     if (!this.host.minSelectedDate || !this.host.maxSelectedDate) {
       return undefined;
     }
 
-    return `year:[${this.host.minSelectedDate} TO ${this.host.maxSelectedDate}]`;
+    const dateField = dateFilterField(
+      this.host.minSelectedDate,
+      this.host.maxSelectedDate,
+    );
+    return `${dateField}:[${this.host.minSelectedDate} TO ${this.host.maxSelectedDate}]`;
   }
 
   private get sortFilterQueries(): string {
@@ -1069,10 +1077,11 @@ export class CollectionBrowserDataSource
       success.response;
     this.aggregations = aggregations;
 
-    this.histogramAggregation =
-      this.host.searchType === SearchType.TV
-        ? aggregations?.date_histogram
-        : aggregations?.year_histogram;
+    const useDateHistogram =
+      this.host.searchType === SearchType.TV || this.host.isTVCollection;
+    this.histogramAggregation = useDateHistogram
+      ? (aggregations?.date_histogram ?? aggregations?.year_histogram)
+      : aggregations?.year_histogram;
 
     if (collectionTitles) {
       for (const [id, title] of Object.entries(collectionTitles)) {

package/src/restoration-state-handler.ts

@@ -14,6 +14,7 @@ import {
   tvClipURLParamsToFilters,
 } from './models';
 import { arrayEquals } from './utils/array-equals';
+import { dateFilterField } from './utils/date-filter-field';
 
 export interface RestorationState {
   displayMode?: CollectionDisplayMode;
@@ -190,11 +191,10 @@ export class RestorationStateHandler
       }
     }
 
-    const dateField =
-      state.minSelectedDate?.includes('-') ||
-      state.maxSelectedDate?.includes('-')
-        ? 'date'
-        : 'year';
+    const dateField = dateFilterField(
+      state.minSelectedDate,
+      state.maxSelectedDate,
+    );
 
     if (state.minSelectedDate && state.maxSelectedDate) {
       newParams.append(

package/src/styles/tile-action-styles.ts

@@ -0,0 +1,59 @@
+import { css } from 'lit';
+
+/**
+ * Shared styles for tile action buttons rendered in grid, list-detail, and
+ * list-compact display modes. Layout positioning is handled by each tile
+ * component; these styles cover only the button appearance and the row
+ * container's default flex behavior.
+ *
+ * Customizable via CSS custom properties:
+ *  - `--tileActionColor` (defaults to --primaryErrorCTAFill, then #d9534f)
+ *  - `--tileActionBg` (default: #fff)
+ *  - `--tileActionBorderColor` (defaults to --primaryErrorCTAFill, then #d9534f)
+ *  - `--tileActionHoverBg` (defaults to --primaryErrorCTAFillRGB at 20% alpha)
+ *  - `--tileActionHoverColor` (defaults to --tileActionColor)
+ */
+export const tileActionStyles = css`
+  .tile-actions {
+    flex-shrink: 0;
+    display: flex;
+    gap: var(--tileActionGap, 0);
+  }
+
+  .tile-action-btn {
+    flex: 1;
+    padding: 6px 5px;
+    border: 2px solid
+      var(--tileActionBorderColor, var(--primaryErrorCTAFill, #d9534f));
+    border-radius: var(--tileActionBorderRadius, 0);
+    /* Inherit from the surrounding tile rather than the UA default for <button> */
+    font-family: inherit;
+    font-size: 1.2rem;
+    font-weight: bold;
+    cursor: pointer;
+    color: var(--tileActionColor, var(--primaryErrorCTAFill, #d9534f));
+    background: var(--tileActionBg, #fff);
+    transition:
+      background 0.15s,
+      color 0.15s;
+  }
+
+  /*
+   * When buttons are flush against each other (no gap), overlap their shared
+   * edge by 1px so adjacent borders don't double up.
+   */
+  .tile-action-btn + .tile-action-btn {
+    margin-left: -1px;
+  }
+
+  .tile-action-btn:hover {
+    background: var(
+      --tileActionHoverBg,
+      rgba(var(--primaryErrorCTAFillRGB, 229, 28, 38), 0.2)
+    );
+    color: var(
+      --tileActionHoverColor,
+      var(--tileActionColor, var(--primaryErrorCTAFill, #d9534f))
+    );
+  }
+`;

package/src/tiles/base-tile-component.ts

@@ -1,13 +1,18 @@
-import { LitElement, PropertyValues } from 'lit';
+import { html, LitElement, nothing, PropertyValues, TemplateResult } from 'lit';
 import { property } from 'lit/decorators.js';
+import { classMap } from 'lit/directives/class-map.js';
 import type { SortParam } from '@internetarchive/search-service';
 import { TileDisplayValueProvider } from './tile-display-value-provider';
 import type { TileModel } from '../models';
 import { DateFormat, formatDate } from '../utils/format-date';
+import type { TileAction } from './models';
 
 export abstract class BaseTileComponent extends LitElement {
   @property({ type: Object }) model?: TileModel;
 
+  /** Action buttons to display on this tile (rendered by subclasses) */
+  @property({ type: Array }) tileActions: TileAction[] = [];
+
   @property({ type: Number }) currentWidth?: number;
 
   @property({ type: Number }) currentHeight?: number;
@@ -62,4 +67,58 @@ export abstract class BaseTileComponent extends LitElement {
     const { useLocalTime } = this;
     return formatDate(date, format, { useLocalTime });
   }
+
+  /**
+   * Renders the action buttons configured for this tile, or `nothing` if
+   * there are none. Optional `extraClass` is appended to the container's
+   * class list so subclasses can target their own layout tweaks.
+   */
+  protected renderTileActions(
+    extraClass: string = '',
+  ): TemplateResult | typeof nothing {
+    if (!this.tileActions.length) return nothing;
+
+    const containerClasses = classMap({
+      'tile-actions': true,
+      ...(extraClass && { [extraClass]: true }),
+    });
+
+    return html`
+      <div class=${containerClasses}>
+        ${this.tileActions.map(
+          action => html`
+            <button
+              class="tile-action-btn"
+              @click=${(e: Event) => this.handleTileActionClick(e, action)}
+            >
+              ${action.label}
+            </button>
+          `,
+        )}
+      </div>
+    `;
+  }
+
+  /**
+   * Click handler for tile action buttons. Stops propagation so the click
+   * doesn't activate a wrapping tile link, and dispatches a
+   * `tileActionClicked` event (bubbling + composed) carrying the action ID
+   * and the tile model.
+   */
+  protected handleTileActionClick(e: Event, action: TileAction): void {
+    e.preventDefault();
+    e.stopPropagation();
+    // Pre-set the hover pane controller's clicking flag so that focus
+    // restoration after a consumer-opened modal won't trigger the hover pane.
+    this.dispatchEvent(
+      new PointerEvent('pointerdown', { bubbles: true, composed: true }),
+    );
+    this.dispatchEvent(
+      new CustomEvent('tileActionClicked', {
+        detail: { actionId: action.id, model: this.model },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
 }

package/src/tiles/grid/item-tile.ts

@@ -24,6 +24,7 @@ export class ItemTile extends BaseTileComponent {
   /*
    * Reactive properties inherited from BaseTileComponent:
    *  - model?: TileModel;
+   *  - tileActions: TileAction[] = [];
    *  - currentWidth?: number;
    *  - currentHeight?: number;
    *  - baseNavigationUrl?: string;