@mcp-b/web-components 0.2.0

package/dist/pagination-6z2qcf3U.d.ts

@@ -0,0 +1,322 @@
+import { CSSResultGroup, PropertyValues } from "lit";
+import { SigveloElement } from "@mcp-b/wc-support/base/sigvelo-element";
+
+//#region src/components/pagination/pagination.d.ts
+/**
+ * <sigvelo-pagination>
+ *
+ * @summary Splits content into numbered pages so users can navigate datasets in manageable chunks.
+ * @tag sigvelo-pagination
+ * @documentation https://design-system.sigvelo.com/docs/components/pagination
+ * @status stable
+ * @since 1.0
+ *
+ * @dependency sigvelo-icon
+ *
+ * @slot previous-icon - A custom icon to use for the previous button.
+ * @slot next-icon - A custom icon to use for the next button.
+ * @slot jump-backward-icon - A custom icon to use for the jump backward button.
+ * @slot jump-forward-icon - A custom icon to use for jump forward button.
+ *
+ * @event sigvelo-before-page-change - Emitted when the page is going to change but before it actually changes. Calling
+ *  `event.preventDefault()` will prevent the page from changing. Inspect `event.detail` to get the `currentPage` and
+ *  `requestedPage` properties.
+ * @event sigvelo-page-change - Emitted after the page has been changed and the UI has been updated.
+ *
+ * @csspart nav - The navigation container, a `<nav>` element.
+ * @csspart list - The list that contains the pagination items, a `<ul>` element.
+ * @csspart item - A pagination item, an `<li>` element.
+ * @csspart button - A pagination button, a `<button>` or an `<a>` element.
+ * @csspart button-first - The button that navigates to the first page.
+ * @csspart button-previous - The button that navigates to the previous page.
+ * @csspart button-next - The button that navigates to the next page.
+ * @csspart button-last - The button that navigates to the last page.
+ * @csspart button-page - A button that navigates to a specific page.
+ * @csspart button-current - The button that represents the current page.
+ * @csspart button-jump-backward - The jump backward button.
+ * @csspart button-jump-forward - The jump forward button.
+ * @csspart range - The page range that shows the page when viewed in the compact format, e.g. "1 of 10".
+ *
+ * @cssstate disabled - Applied when the pagination is disabled.
+ *
+ * @example Default
+ * ```html
+ * <sigvelo-pagination total-pages="5"></sigvelo-pagination>
+ * ```
+ *
+ * @example Setting the number of pages
+ * Use the `total-pages` attribute to set the total number of pages available.
+ *
+ * ```html
+ * <sigvelo-pagination total-pages="20"></sigvelo-pagination>
+ * ```
+ *
+ * @example Setting the initial page
+ * Use the `page` attribute to set the initial page that's selected.
+ *
+ * ```html
+ * <sigvelo-pagination total-pages="5" page="3"></sigvelo-pagination>
+ * ```
+ *
+ * @example Responding to page changes
+ * When the user changes the page, the `sigvelo-page-change` event will be emitted. You can listen to this event to update the view or redirect the user to the appropriate destination.
+ *
+ * ```html
+ * <sigvelo-pagination
+ *   total-pages="10"
+ *   page="1"
+ *   id="pagination__responding"
+ * ></sigvelo-pagination>
+ *
+ * <script>
+ *   const pagination = document.getElementById('pagination__responding');
+ *
+ *   pagination.addEventListener('sigvelo-page-change', () => {
+ *     //
+ *     // Update the view here
+ *     //
+ *     console.log(`Showing page ${pagination.page}`);
+ *
+ *     //
+ *     // Alternatively, you can send the user to a URL:
+ *     //
+ *     // location.href = `/page/${pagination.page}`
+ *     //
+ *   });
+ * </script>
+ * ```
+ *
+ * @example Changing the page programmatically
+ * Set the `page` property to any valid page to change the current page. Note that programmatic changes _will not_ dispatch page change events.
+ *
+ * ```html
+ * <sigvelo-pagination
+ *   total-pages="10"
+ *   page="1"
+ *   id="pagination__setting"
+ * ></sigvelo-pagination>
+ *
+ * <sigvelo-select label="Page" value="1" style="max-width: 100px; margin-block-start: 1.5rem;">
+ *   <option value="1">1</option>
+ *   <option value="2">2</option>
+ *   <option value="3">3</option>
+ *   <option value="4">4</option>
+ *   <option value="5">5</option>
+ *   <option value="6">6</option>
+ *   <option value="7">7</option>
+ *   <option value="8">8</option>
+ *   <option value="9">9</option>
+ *   <option value="10">10</option>
+ * </sigvelo-select>
+ *
+ * <script>
+ *   const pagination = document.getElementById('pagination__setting');
+ *   const select = pagination.nextElementSibling;
+ *
+ *   select.addEventListener('input', () => {
+ *     pagination.page = select.value;
+ *   });
+ *
+ *   pagination.addEventListener('sigvelo-page-change', () => {
+ *     select.value = pagination.page;
+ *   });
+ * </script>
+ * ```
+ *
+ * @example Rendering links instead of buttons
+ * By default, the pagination component renders `<button>` elements internally. To have it render links instead, set the `link-formatter` attribute to a URL with a `{page}` placeholder that corresponds to the target page, e.g. `/path/to/{page}`.
+ *
+ * ```html
+ * <sigvelo-pagination
+ *   total-pages="10"
+ *   page="5"
+ *   link-formatter="https://example.com/path/to/{page}"
+ * ></sigvelo-pagination>
+ * ```
+ *
+ * For more control over the URL, you can set the `linkFormatter` property to a JavaScript function that accepts a page number and returns a URL.
+ *
+ * ```html
+ * <sigvelo-pagination id="pagination__links" total-pages="5"></sigvelo-pagination>
+ *
+ * <script>
+ *   const pagination = document.getElementById('pagination__links');
+ *
+ *   pagination.linkFormatter = page => `https://example.com/path/to/${page}`;
+ * </script>
+ * ```
+ *
+ * **Note:** When a link formatter is provided, users will be redirected to the corresponding URL when they select a page. In this case, the pagination component _will not_ update dynamically. This is the intended behavior when using links.
+ *
+ * @example Changing the format
+ * Set the `format` attribute to `compact` or `standard` to change the pagination's format.
+ *
+ * ```html
+ * <sigvelo-pagination
+ *   format="compact"
+ *   total-pages="5"
+ *   id="pagination__format"
+ * ></sigvelo-pagination>
+ *
+ * <sigvelo-radio label="Format" value="compact" class="sigvelo-vh-label" style="margin-block-start: 1.5rem;">
+ *   <sigvelo-radio-item value="compact">Compact</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="standard">Standard</sigvelo-radio-item>
+ * </sigvelo-select>
+ *
+ * <script>
+ *   const pagination = document.getElementById('pagination__format');
+ *   const radio = pagination.nextElementSibling;
+ *
+ *   radio.addEventListener('input', () => {
+ *     pagination.format = radio.value;
+ *   });
+ * </script>
+ * ```
+ *
+ * @example Changing the variant
+ * Set the `variant` attribute to `normal`, `filled`, or `unstyled` to change the pagination's variant.
+ *
+ * ```html
+ * <sigvelo-pagination variant="normal" total-pages="5"></sigvelo-pagination>
+ * <sigvelo-pagination variant="filled" total-pages="5"></sigvelo-pagination>
+ * <sigvelo-pagination variant="unstyled" total-pages="5"></sigvelo-pagination>
+ * ```
+ *
+ * @example Changing the number of buttons
+ * Use the `siblings` attribute to control the number of pages that show on each side of the current page. The default is 3. The minimum is 2.
+ *
+ * ```html
+ * <sigvelo-pagination siblings="2" total-pages="20" page="10"></sigvelo-pagination>
+ * <sigvelo-pagination siblings="3" total-pages="20" page="10"></sigvelo-pagination>
+ * <sigvelo-pagination siblings="4" total-pages="20" page="10"></sigvelo-pagination>
+ * ```
+ *
+ * @example Changing the size
+ * Pagination controls are sized relative to the current font size. To change their size, apply `font-size` to the pagination or an ancestor element.
+ *
+ * ```html
+ * <sigvelo-pagination
+ *   total-pages="5"
+ *   page="1"
+ *   style="font-size: 0.75rem;"
+ * ></sigvelo-pagination>
+ *
+ * <sigvelo-pagination
+ *   total-pages="5"
+ *   page="1"
+ *   style="font-size: 1rem;"
+ * ></sigvelo-pagination>
+ *
+ * <sigvelo-pagination
+ *   total-pages="5"
+ *   page="1"
+ *   style="font-size: 1.25rem;"
+ * ></sigvelo-pagination>
+ * ```
+ *
+ * @example Using custom icons
+ * Use the `previous-icon`, `next-icon`, and `jump-icon` slots to override the default icons.
+ *
+ * ```html
+ * <sigvelo-pagination total-pages="10">
+ *   <sigvelo-icon slot="previous-icon" name="arrow-left"></sigvelo-icon>
+ *   <sigvelo-icon slot="next-icon" name="arrow-right"></sigvelo-icon>
+ *   <sigvelo-icon slot="jump-backward-icon" name="chevrons-left"></sigvelo-icon>
+ *   <sigvelo-icon slot="jump-forward-icon" name="chevrons-right"></sigvelo-icon>
+ * </sigvelo-pagination>
+ * ```
+ *
+ * @example Removing nav buttons
+ * Use `without-nav` to remove the previous and next navigation buttons.
+ *
+ * ```html
+ * <sigvelo-pagination
+ *   total-pages="10"
+ *   page="1"
+ *   without-nav
+ * ></sigvelo-pagination>
+ * ```
+ *
+ * @example Disabling
+ * Add the `disabled` attribute to disable the pagination control.
+ *
+ * ```html
+ * <sigvelo-pagination
+ *   total-pages="10"
+ *   page="1"
+ *   disabled
+ * ></sigvelo-pagination>
+ * ```
+ *
+ * @example Styling pagination
+ * Pagination controls come with a simple, minimal appearance. Feel free to customize them with your own styles.
+ *
+ * ```html
+ * <sigvelo-pagination total-pages="10" page="5" variant="unstyled" id="pagination__styling"></sigvelo-pagination>
+ *
+ * <style>
+ *   #pagination__styling {
+ *     &::part(button) {
+ *       border-radius: var(--sigvelo-radius-full);
+ *     }
+ *
+ *     <!-- Light gray circles for previous and next buttons -->
+ *     &::part(button-previous),
+ *     &::part(button-next) {
+ *       background-color: var(--sigvelo-color-neutral-bg-subtle);
+ *     }
+ *
+ *     <!-- The current page is larger and has a subtle gradient -->
+ *     &::part(button-current) {
+ *       background: linear-gradient(45deg, #ff1493, #ff69b4);
+ *       color: white;
+ *       scale: 1.1;
+ *     }
+ *   }
+ * </style>
+ * ```
+ */
+declare class SigveloPagination extends SigveloElement {
+  static styles: CSSResultGroup;
+  private localize;
+  /** A label to use to describe the control to assistive devices. Defaults to "Pagination" when not set. */
+  label: string;
+  /** The total number of pages to show. */
+  totalPages: number;
+  /** The current page. */
+  page: number;
+  /** The number of pages to show on each side of the current page. Minimum 2. */
+  siblings: number;
+  /** The number of pages to increase or decrease when jump buttons are clicked. */
+  jump: number;
+  /** How the pagination will display buttons. */
+  format: "compact" | "standard";
+  /**
+   * A string that, when provided, renders `<a>` elements instead of `<${tag}s>` using this as the link's template.
+   * Use `$page` to indicate the page number, e.g. `"/path/to/$page"`. Alternatively, you can provide a JavaScript
+   * function that accepts a page number and returns a URL.
+   */
+  linkFormatter: string | ((page: number) => string);
+  /** Disables the pagination control. */
+  disabled: boolean;
+  /** Determine's the pagination's variant. */
+  variant: "normal" | "filled" | "unstyled";
+  /** Removes the previous and next buttons. */
+  withoutNav: boolean;
+  willUpdate(changedProperties: PropertyValues<this>): void;
+  updated(changedProperties: PropertyValues<this>): void;
+  /** Changes the current page, emitting a cancellable 'sigvelo-page-change' event. */
+  private changePage;
+  /** Generates the list of pagination items, including pages and jump buttons. */
+  private getPaginationItems;
+  private handleNavClick;
+  private renderLink;
+  render(): import("lit-html").TemplateResult;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    "sigvelo-pagination": SigveloPagination;
+  }
+}
+//#endregion
+export { SigveloPagination as t };