@synergy-design-system/metadata 1.0.0 → 3.0.1

package/data/layers/full/component/component:syn-pagination/components/pagination.component.ts

@@ -0,0 +1,452 @@
+import {
+  type CSSResultGroup,
+  type PropertyValues,
+  html,
+  nothing,
+} from 'lit';
+import { property } from 'lit/decorators.js';
+import { createRef, ref } from 'lit/directives/ref.js';
+import { LocalizeController } from '../../utilities/localize.js';
+import SynergyElement from '../../internal/synergy-element.js';
+import componentStyles from '../../styles/component.styles.js';
+import styles from './pagination.styles.js';
+import SynDivider from '../divider/divider.component.js';
+import SynIconButton from '../icon-button/icon-button.component.js';
+import SynInput from '../input/input.component.js';
+import SynOption from '../option/option.component.js';
+import SynSelect from '../select/select.component.js';
+import {
+  calculatePageItemIndices,
+  calculateTotalPages,
+  clampPage,
+  getMaxOptionCharCount,
+  getPreviousOrDefault,
+  getTotalPages,
+  getTotalPagesCharCount,
+  isValidNonNegativeInteger,
+  isValidPositiveInteger,
+  sanitizePageSizeOptions,
+} from './utility.js';
+import type { SynInputEvent } from '../../events/events.js';
+import { enableDefaultSettings } from '../../utilities/defaultSettings/decorator.js';
+
+/**
+ * @summary <syn-pagination /> provides page navigation, direct page input, and page-size selection for large data sets.
+ *
+ * @documentation https://synergy-design-system.github.io/?path=/docs/components-syn-pagination--docs
+ * @status stable
+ * @since 3.12.0
+ *
+ * @event syn-pagination-page-changed - Emitted when the current page changes
+ * @event syn-pagination-page-size-changed - Emitted when the page size changes
+ *
+ * @csspart base - The component's base wrapper.
+ * @csspart divider - The divider element displayed at the top of the pagination component.
+ * @csspart page-size-select-wrapper - The wrapper element containing the page size select and page item summary.
+ * @csspart page-size-select - The page size select element.
+ * @csspart page-item-summary - The text element displaying the current page item range and total items.
+ * @csspart page-input-section - The section containing the page number input and total pages display.
+ * @csspart page-input - The page number input element.
+ * @csspart navigation - The pagination navigation element.
+ * @csspart navigation-action - The individual navigation action buttons (first, previous, next, last).
+ *
+ * @accessibility
+ * The entire component is wrapped in a semantic `<nav>` landmark with an `aria-label` for screen reader accessibility.
+ * Use the `aria-label` attribute to provide a unique, descriptive label when multiple pagination controls exist on the page.
+ * Example: `<syn-pagination aria-label="Search results pagination"></syn-pagination>`
+ */
+@enableDefaultSettings('SynPagination')
+export default class SynPagination extends SynergyElement {
+  private static readonly DEFAULT_PAGE_SIZE = 25;
+
+  private static readonly DEFAULT_CURRENT_PAGE = 1;
+
+  private static readonly DEFAULT_TOTAL_ITEMS = 0;
+
+  private readonly baseRef = createRef<HTMLElement>();
+
+  private readonly localize = new LocalizeController(this);
+
+  static styles: CSSResultGroup = [
+    componentStyles,
+    styles,
+  ];
+
+  static dependencies = {
+    'syn-divider': SynDivider,
+    'syn-icon-button': SynIconButton,
+    'syn-input': SynInput,
+    'syn-option': SynOption,
+    'syn-select': SynSelect,
+  };
+
+  /**
+   * When true, a divider is displayed at the top of the pagination component.
+   */
+  @property({ type: Boolean }) divider = false;
+
+  /**
+   * When true, the pagination controls are disabled and non-interactive.
+   */
+  @property({ reflect: true, type: Boolean }) disabled = false;
+
+  /**
+   * The size of the pagination controls.
+   */
+  @property({ reflect: true }) size: 'small' | 'medium' | 'large' = 'medium';
+
+  /**
+   * The current page number. The default value is 1.
+   * The component will emit a `syn-pagination-page-changed` event whenever the page changes, allowing you to respond to page changes in your application.
+   */
+  @property({ attribute: 'current-page', reflect: true, type: Number }) currentPage = 1;
+
+  /**
+   * The number of items to display per page. The default value is 25.
+   * The component will emit a `syn-pagination-page-size-changed` event whenever the page size changes, allowing you to respond to page size changes in your application.
+   */
+  @property({ attribute: 'page-size', reflect: true, type: Number }) pageSize = 25;
+
+  /**
+   * An array of numbers representing the available options for the number of items to display per page. The default value is [10, 25, 50, 100].
+   * The component will use this array to populate the rows-per-page selector, allowing users to choose from the specified options.
+   */
+  @property({
+    attribute: 'page-size-options',
+    converter: {
+      fromAttribute: (value: string) => value
+        .split(',')
+        .map(val => {
+          const num = parseInt(val.trim(), 10);
+          return Number.isSafeInteger(num) ? num : null;
+        })
+        .filter(Boolean),
+    },
+    type: Array,
+  }) pageSizeOptions: number[] = [10, 25, 50, 100];
+
+  /**
+   * Total amount of items. The component will use this value to calculate the total number of pages based on the selected rows per page.
+   */
+  @property({ attribute: 'total-items', reflect: true, type: Number }) totalItems = 0;
+
+  /**
+   * The pagination variant to use. The "full" variant includes comprehensive controls for navigating between pages and adjusting the number of displayed rows,
+   * while the "compact" variant offers a streamlined interface with essential navigation controls.
+   * The default value is "full".
+   */
+  @property({ attribute: 'variant', reflect: true }) variant: 'full' | 'compact' = 'full';
+
+  /**
+   * An accessible label for the navigation landmark. Customize for multiple paginations on a page.
+   */
+  @property({ attribute: 'aria-label' }) ariaLabel = 'Pagination';
+
+  private pageChangedViaUserInput(e: SynInputEvent) {
+    const newPage = (e.target as SynInput).valueAsNumber;
+    // Ignore invalid page inputs
+    if (!isValidPositiveInteger(newPage)) {
+      return;
+    }
+    this.updateCurrentPage(newPage);
+  }
+
+  private navigationClicked(event: MouseEvent, newPage: number) {
+    // Blur first so icon-button focus state settles before this render cycle disables it.
+    (event.currentTarget as SynIconButton | null)?.blur();
+    this.updateCurrentPage(newPage);
+  }
+
+  private sanitizeInvalidPropertyValues(changed: PropertyValues<this>) {
+    if (changed.has('pageSize') && !isValidPositiveInteger(this.pageSize)) {
+      this.pageSize = getPreviousOrDefault(
+        changed,
+        'pageSize',
+        SynPagination.DEFAULT_PAGE_SIZE,
+        isValidPositiveInteger,
+      );
+    }
+
+    if (changed.has('currentPage') && !isValidPositiveInteger(this.currentPage)) {
+      this.currentPage = getPreviousOrDefault(
+        changed,
+        'currentPage',
+        SynPagination.DEFAULT_CURRENT_PAGE,
+        isValidPositiveInteger,
+      );
+    }
+
+    if (changed.has('totalItems') && !isValidNonNegativeInteger(this.totalItems)) {
+      this.totalItems = getPreviousOrDefault(
+        changed,
+        'totalItems',
+        SynPagination.DEFAULT_TOTAL_ITEMS,
+        isValidNonNegativeInteger,
+      );
+    }
+
+    if (changed.has('pageSizeOptions')) {
+      const sanitizedPageSizeOptions = sanitizePageSizeOptions(this.pageSizeOptions);
+      const hasChanged = this.pageSizeOptions.length !== sanitizedPageSizeOptions.length
+        || this.pageSizeOptions.some((option, index) => option !== sanitizedPageSizeOptions[index]);
+
+      if (hasChanged) {
+        this.pageSizeOptions = sanitizedPageSizeOptions;
+      }
+    }
+  }
+
+  /**
+   * Updates the current page number and emits a "syn-pagination-page-changed" event with the new and previous page numbers.
+    * This method is called when the page number is changed via the page input or the navigation buttons.
+   */
+  private updateCurrentPage(newPage: number) {
+    const totalPages = getTotalPages(this.pageSize, this.totalItems);
+    const safeNewPage = clampPage(newPage, totalPages);
+    const { currentPage } = this;
+
+    if (safeNewPage === currentPage) {
+      return;
+    }
+
+    this.emit('syn-pagination-page-changed', {
+      detail: {
+        currentPage: safeNewPage,
+        previousPage: currentPage,
+      },
+    });
+
+    this.currentPage = safeNewPage;
+  }
+
+  /**
+   * Called when the page size is changed via the page size select.
+   * Emits a `syn-pagination-page-size-changed` event with the new and previous page sizes.
+   */
+  private pageSizeChanged(e: SynInputEvent) {
+    const { currentPage, pageSize } = this;
+    const currentTarget = e.target as SynSelect;
+    const { value } = currentTarget;
+    const nextPageSize = parseInt(value as string, 10);
+
+    // Validate the new page size before applying it
+    if (!Number.isSafeInteger(nextPageSize) || nextPageSize <= 0) return;
+
+    // When we switch from a smaller value to a larger one,
+    // we also have to adjust the current page marker.
+    const oldStartIndex = (currentPage - 1) * pageSize + 1;
+    const nextTotalPages = getTotalPages(nextPageSize, this.totalItems);
+
+    const nextPage = clampPage(
+      Math.floor((oldStartIndex - 1) / nextPageSize) + 1,
+      nextTotalPages,
+    );
+
+    this.pageSize = nextPageSize;
+    this.currentPage = nextPage;
+
+    this.emit('syn-pagination-page-size-changed', {
+      detail: {
+        currentPageSize: nextPageSize,
+        previousPageSize: pageSize,
+      },
+    });
+
+    if (nextPage !== currentPage) {
+      this.emit('syn-pagination-page-changed', {
+        detail: {
+          currentPage: nextPage,
+          previousPage: currentPage,
+        },
+      });
+    }
+  }
+
+  protected willUpdate(changed: PropertyValues<this>) {
+    super.willUpdate(changed);
+
+    this.sanitizeInvalidPropertyValues(changed);
+
+    const previousPageSizeOptions = changed.get('pageSizeOptions');
+    const hasPreviousPageSizeOptions = Array.isArray(previousPageSizeOptions);
+
+    if (hasPreviousPageSizeOptions && !this.pageSizeOptions.includes(this.pageSize)) {
+      const nextPageSize = this.pageSizeOptions[0];
+      const oldStartIndex = (this.currentPage - 1) * this.pageSize + 1;
+      const nextTotalPages = getTotalPages(nextPageSize, this.totalItems);
+
+      const nextPage = clampPage(
+        Math.floor((oldStartIndex - 1) / nextPageSize) + 1,
+        nextTotalPages,
+      );
+
+      this.pageSize = nextPageSize;
+      this.currentPage = nextPage;
+    }
+
+    if (changed.has('currentPage') || changed.has('pageSize') || changed.has('totalItems')) {
+      // If the current page exceeds the total number of pages based on the new page size or total items,
+      // we need to adjust it to ensure it remains within valid bounds.
+      const totalPages = getTotalPages(this.pageSize, this.totalItems);
+      const clamped = clampPage(this.currentPage, totalPages);
+      if (clamped !== this.currentPage) {
+        this.currentPage = clamped;
+      }
+    }
+  }
+
+  protected updated(changed: PropertyValues<this>) {
+    super.updated(changed);
+
+    // When the size of available options or the page size changes,
+    // we have to adjust the width of our page size select/input controls.
+    if (changed.has('pageSizeOptions') || changed.has('pageSize') || changed.has('totalItems')) {
+      const maxOptionCharCount = getMaxOptionCharCount(this.pageSizeOptions);
+      const totalPagesCharCount = getTotalPagesCharCount(this.pageSize, this.totalItems);
+      const baseElement = this.baseRef.value;
+
+      if (baseElement) {
+        baseElement.style.setProperty('--pagination-page-size-option-char-count', String(maxOptionCharCount));
+        baseElement.style.setProperty('--pagination-total-pages-char-count', String(totalPagesCharCount));
+      }
+    }
+  }
+
+  render() {
+    // List of total pages.
+    // Used to determine the disabled state of navigation buttons and to calculate the page item indices for display.
+    const totalPages = calculateTotalPages(this.totalItems, this.pageSize);
+
+    // Determine if we're in compact mode to conditionally apply styles and layout adjustments.
+    const isCompact = this.variant === 'compact';
+
+    // Condition to determine if the pagination controls should be disabled.
+    const isDisabled = this.disabled || totalPages === 0;
+
+    // Calculate the start and end item indices for the current page to display in the pagination summary (e.g., "11-20 of 100 items").
+    const pageItemIndices = calculatePageItemIndices(this.totalItems, this.pageSize, this.currentPage);
+
+    // If the current page size is not included in the available options,
+    // we select the first option as the default value to ensure the select input displays a valid option.
+    const selectedPageSizeOption = this.pageSizeOptions.includes(this.pageSize)
+      ? this.pageSize
+      : this.pageSizeOptions[0];
+
+    const isFirstPage = this.currentPage === 1;
+    const isLastPage = this.currentPage === totalPages;
+
+    /* eslint-disable @typescript-eslint/unbound-method */
+    return html`
+      ${this.divider ? html`<syn-divider part="divider"></syn-divider>` : nothing}
+      <nav
+        aria-label=${this.ariaLabel}
+        class="pagination"
+        part="base"
+        ${ref(this.baseRef)}
+      >
+        ${!isCompact ? html`
+          <div class="pagination__page-size-select-wrapper" part="page-size-select-wrapper">
+            <syn-select
+              class="pagination__page-size-select"
+              ?disabled=${isDisabled}
+              label=${this.localize.term('paginationItemsPerPage')}
+              part="page-size-select"
+              value=${selectedPageSizeOption}
+              size=${this.size}
+              @syn-change=${this.pageSizeChanged}
+            >
+              ${this.pageSizeOptions.map(option => html`
+                <syn-option value="${option}">
+                  ${option}
+                </syn-option>
+              `)}
+            </syn-select>
+            <!-- /.pagination__page-size-select -->
+
+            <span part="page-item-summary">
+              ${this.localize.term(
+                'paginationItemSummary',
+                pageItemIndices.startIndex,
+                pageItemIndices.endIndex,
+                this.totalItems,
+              )}
+            </span>
+            <!-- /.pagination__page-item-summary -->
+          </div>
+          <!-- /.pagination__page-size-select-wrapper -->
+        `: nothing}
+
+        <div class="pagination__navigation" part="navigation">
+          <section>
+            <syn-icon-button
+              @click=${(e: MouseEvent) => this.navigationClicked(e, 1)}
+              color="primary"
+              ?disabled=${isFirstPage || isDisabled}
+              label=${this.localize.term('paginationFirstPage')}
+              library="system"
+              name="first-page"
+              part="navigation-action"
+              size=${this.size}
+            ></syn-icon-button>
+
+            <syn-icon-button
+              @click=${(e: MouseEvent) => this.navigationClicked(e, this.currentPage - 1)}
+              color="primary"
+              ?disabled=${isFirstPage || isDisabled}
+              label=${this.localize.term('paginationPreviousPage')}
+              library="system"
+              name="previous-page"
+              part="navigation-action"
+              size=${this.size}
+            ></syn-icon-button>
+          </section>
+
+          <section part="page-input-section">
+            <syn-input
+              class="pagination__page-input"
+              ?disabled=${isDisabled}
+              label=${this.localize.term('paginationInputLabel')}
+              max=${totalPages}
+              min="1"
+              no-spin-buttons
+              numeric-strategy="modern"
+              part="page-input"
+              size=${this.size}
+              @syn-change=${this.pageChangedViaUserInput}
+              type="number"
+              value=${this.currentPage}
+            ></syn-input>
+            
+            <span>${this.localize.term('paginationOfTotalPages', totalPages)}</span>
+          </section>
+
+          <section>
+            <syn-icon-button
+              @click=${(e: MouseEvent) => this.navigationClicked(e, this.currentPage + 1)}
+              color="primary"
+              ?disabled=${isLastPage || isDisabled}
+              label=${this.localize.term('paginationNextPage')}
+              library="system"
+              name="next-page"
+              part="navigation-action"
+              size=${this.size}
+            ></syn-icon-button>
+
+            <syn-icon-button
+              @click=${(e: MouseEvent) => this.navigationClicked(e, totalPages)}
+              color="primary"
+              ?disabled=${isLastPage || isDisabled}
+              label=${this.localize.term('paginationLastPage')}
+              library="system"
+              name="last-page"
+              part="navigation-action"
+              size=${this.size}
+            ></syn-icon-button>
+          </section>
+        </div>
+        <!-- /.pagination__navigation -->
+      </nav>
+    `;
+    /* eslint-enable @typescript-eslint/unbound-method */
+  }
+}

package/data/layers/full/component/component:syn-pagination/components/pagination.styles.ts

@@ -0,0 +1,128 @@
+import { css } from 'lit';
+
+export default css`
+  :host {
+    display: block;
+  }
+
+  .pagination {
+    --base-font: var(--syn-body-medium-regular);
+    --base-gap: var(--syn-spacing-small);
+    --navigation-gap: var(--syn-spacing-small);
+    --pagination-page-size-option-char-count: 2;
+    --pagination-total-pages-char-count: 3;
+
+    align-items: center;
+    display: flex;
+    flex-wrap: wrap;
+    font: var(--base-font);
+    gap: var(--base-gap) var(--syn-spacing-large);
+  }
+
+  /* Sizes */
+  :host([size="small"]) .pagination {
+    --base-gap: var(--syn-spacing-x-small);
+    --base-font: var(--syn-body-small-regular);
+  }
+
+  :host([size="large"]) .pagination {
+    --base-gap: var(--syn-spacing-medium);
+    --base-font: var(--syn-body-large-regular);
+  }
+
+  /* Divider */
+  syn-divider {
+    --divider-spacing: var(--syn-spacing-small); 
+    --spacing: 0 auto var(--divider-spacing);
+  }
+
+  :host([size="small"]) syn-divider {
+    --divider-spacing: var(--syn-spacing-x-small); 
+  }
+
+  :host([size="large"]) syn-divider {
+    --divider-spacing: var(--syn-spacing-medium);
+  }
+
+  /* Select */
+  .pagination__page-size-select-wrapper {
+    align-items: center;
+    display: flex;
+    gap: var(--base-gap);
+  }
+
+  .pagination__page-size-select::part(form-control) {
+    align-items: center;
+    display: flex;
+    gap: var(--base-gap);
+  }
+
+  .pagination__page-size-select::part(form-control-label) {
+    font: var(--base-font);
+    margin-bottom: 0;
+  }
+
+  .pagination__page-size-select::part(display-input) {
+    width: calc((var(--pagination-page-size-option-char-count) * 1ch) + 1ch);
+  }
+
+  /* Navigation */
+  .pagination__navigation {
+    align-items: center;
+    display: flex;
+    flex: 1;
+    flex-wrap: nowrap;
+    gap: var(--navigation-gap);
+    justify-content: end;
+  }
+
+  .pagination__navigation > section {
+    align-items: center;
+    display: flex;
+    flex-wrap: nowrap;
+  }
+
+  .pagination__page-input {
+    margin-inline-end: var(--navigation-gap);
+  }
+
+  .pagination__page-input::part(input) {
+    text-align: center;
+    width: calc((var(--pagination-total-pages-char-count) * 1ch) + 3ch);
+  }
+
+  /**
+   * Make sure to hide the label of the page input, but keep it accessible for screen readers.
+   * We can't use the label slot of syn-input for this, because it would mess with the layout.
+   */
+  .pagination__page-input::part(form-control-label) {
+    border: 0;
+    /* stylelint-disable-next-line property-no-deprecated */
+    clip: rect(0, 0, 0, 0);
+    height: 1px;
+    margin: -1px;
+    overflow: hidden;
+    padding: 0;
+    position: absolute;
+    white-space: nowrap;
+    width: 1px;
+  }
+
+  /* Compact Version */
+  :host([variant="compact"]) .pagination__navigation {
+    justify-content: center;
+  }
+
+  /* Adjustments for really small container widths */
+  @supports (container-type: inline-size) {
+    :host {
+      container-type: inline-size;
+    }
+
+    @container (max-width: 400px) {
+      .pagination__navigation {
+        justify-content: center;
+      }
+    }
+  }
+`;

package/data/layers/full/component/component:syn-pagination/components/pagination.ts

@@ -0,0 +1,12 @@
+import SynPagination from './pagination.component.js';
+
+export * from './pagination.component.js';
+export default SynPagination;
+
+SynPagination.define('syn-pagination');
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'syn-pagination': SynPagination;
+  }
+}