@ds-mo/ui 14.18.1 → 14.19.0

package/dist/mcp-data/registry/pagination.json

@@ -2,7 +2,7 @@
   "$schema": "https://ui.shadcn.com/schema/registry-item.json",
   "name": "pagination",
   "title": "Pagination",
-  "description": "Controlled fixed or fitted page-size, compact range, and first/previous/next/last navigation for application-owned data windows.",
+  "description": "Controlled fixed or fitted page-size, compact range, adjacent-page navigation, and optional first/last controls for application-owned data windows.",
   "type": "registry:ui",
   "meta": {
     "library": "@ds-mo/ui",
@@ -13,14 +13,15 @@
     "intent": {
       "audience": "general",
       "status": "stable",
-      "summary": "Controlled fixed or fitted page-size, compact range, and first/previous/next/last navigation for application-owned data windows.",
+      "summary": "Controlled fixed or fitted page-size, compact range, adjacent-page navigation, and optional first/last controls for application-owned data windows.",
       "useWhen": [
         "A result set is divided into discrete pages and the application owns fetching or slicing each page.",
-        "A table or list needs a compact page-size selector, result range, and boundary-aware navigation."
+        "A table or list needs a compact page-size selector, result range, and boundary-aware navigation.",
+        "Direct first-page and last-page navigation is useful enough to opt into alongside the default Previous and Next controls."
       ],
       "avoidWhen": [
         "More results append to one continuous list; use the owning component's incremental-loading behavior instead.",
-        "Only previous and next navigation is meaningful and the total result count is unknown."
+        "The total result count is unknown; use an incremental-loading pattern instead."
       ],
       "commonlyComposedWith": [
         "component:ds-table",
@@ -31,18 +32,20 @@
         "The component renders a named navigation region, gives its compact page-size noun a complete accessible label, and gives every icon-only boundary control an explicit page action name.",
         "The visible page-size cluster states the localized noun, selected size, and current-page count of total, for example Rows: [25] 25 of 500. The page position uses compact ‘of’ phrasing, for example 1 of 20. A polite atomic status update retains the complete current range and ‘Page’ phrasing with the localized item noun.",
         "Left and Right Arrow request the adjacent page while focus is within pagination navigation controls. The page-size combobox retains its own arrow-key behavior.",
-        "Inactive boundary controls and every control during loading remain non-interactive while retaining their accessible names."
+        "Inactive boundary controls and every control during loading remain non-interactive while retaining their accessible names.",
+        "showFirstLastButtons adds explicitly named First page and Last page controls; Previous and Next remain present in either mode."
       ],
       "states": [
         "pageIndex, numeric effective pageSize, pageSizeMode, totalItems, and pageSizeOptions are controlled inputs. dsChange reports the complete next pagination state, previous index, size, and mode, and whether the request changed the page, page size, or fitted capacity; it never mutates controlled inputs.",
         "Page-size changes request the first page. Out-of-range page indexes and invalid numeric inputs normalize only for presentation; the owner remains authoritative.",
         "Zero results display 0–0 of 0 and Page 1 of 1. A partial final page caps the visible range at totalItems.",
         "loading preserves the full pagination surface, applies aria-busy to the navigation region, and prevents page or page-size requests.",
-        "fitToPage appends a Fit to page choice. fitPageSize supplies its effective whole-item capacity; the closed trigger says Fit while the range continues to expose the resulting count. fitToPageInactive keeps that choice visible but unavailable when fitting is not meaningful for the current data shape. Pagination does not measure layouts itself."
+        "fitToPage appends a Fit to page choice. fitPageSize supplies its effective whole-item capacity; the closed trigger says Fit while the range continues to expose the resulting count. fitToPageInactive keeps that choice visible but unavailable when fitting is not meaningful for the current data shape. Pagination does not measure layouts itself.",
+        "showFirstLastButtons defaults to false. Enable it when direct jumps to both result boundaries materially help the workflow."
       ],
       "responsiveBehavior": [
-        "The full-width controls remain on one line with noun, selected size, current-page count of total, a vertical divider, page position, and first, previous, next, and last navigation.",
-        "Inside a ds-table container narrower than 900px, pagination hides the visible current-page count and first/last boundary controls while retaining the page-size noun and selector plus previous, page position, and next. The complete current range remains available to assistive technology."
+        "The full-width controls remain on one line with noun, selected size, current-page count of total, a vertical divider, page position, Previous and Next, plus optional First and Last navigation.",
+        "Inside a ds-table container narrower than 900px, pagination hides the visible current-page count and any opted-in first/last controls while retaining the page-size noun and selector plus Previous, page position, and Next. The complete current range remains available to assistive technology."
       ],
       "frameworkCaveats": {
         "customElements": [
@@ -187,6 +190,15 @@
           "mutable": false,
           "description": "Available page sizes. Assign arrays through JavaScript."
         },
+        "showFirstLastButtons": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "show-first-last-buttons",
+          "default": "false",
+          "required": false,
+          "mutable": false,
+          "description": "Include direct first-page and last-page controls."
+        },
         "totalItems": {
           "type": "number",
           "resolvedType": "number",
@@ -334,6 +346,15 @@
         "mutable": false,
         "description": "Available page sizes. Assign arrays through JavaScript."
       },
+      "showFirstLastButtons": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "show-first-last-buttons",
+        "default": "false",
+        "required": false,
+        "mutable": false,
+        "description": "Include direct first-page and last-page controls."
+      },
       "totalItems": {
         "type": "number",
         "resolvedType": "number",
@@ -409,7 +430,7 @@
     },
     {
       "path": "src/wc/components/Pagination/Pagination.tsx",
-      "content": "import { Component, Element, Event, EventEmitter, h, Host, Prop, State } from '@stencil/core';\nimport { observeTableCaptionCompact } from '../../utils/table-caption-compact';\nimport { resolvePaginationState } from './pagination-model';\nimport type {\n  PaginationChangeDetail,\n  PaginationPageSizeMode,\n} from './pagination-types';\n\nlet paginationId = 0;\n\n@Component({\n  tag: 'ds-pagination',\n  styleUrl: 'Pagination.css',\n  scoped: true,\n})\nexport class Pagination {\n  @Element() el!: HTMLElement;\n\n  /** Controlled zero-based page index. */\n  @Prop() pageIndex: number = 0;\n  /** Controlled number of top-level items on a full page. */\n  @Prop() pageSize: number = 25;\n  /** Whether pageSize is a fixed choice or a measured Fit snapshot. */\n  @Prop() pageSizeMode: PaginationPageSizeMode = 'fixed';\n  /** Controlled total number of top-level items across every page. */\n  @Prop() totalItems: number = 0;\n  /** Available page sizes. Assign arrays through JavaScript. */\n  @Prop() pageSizeOptions: number[] = [25, 50, 100, 200];\n  /** Include the Fit to page choice. */\n  @Prop() fitToPage: boolean = false;\n  /** Keep the Fit to page choice visible but unavailable. */\n  @Prop() fitToPageInactive: boolean = false;\n  /** Effective whole-item capacity to request when Fit is selected. */\n  @Prop() fitPageSize: number | undefined;\n  /** Full choice-list label for Fit. */\n  @Prop() fitPageSizeLabel: string = 'Fit to page';\n  /** Compact closed-trigger label while Fit is selected. */\n  @Prop() fitPageSizeTriggerLabel: string = 'Fit';\n  /** Localized plural noun used by assistive range announcements. */\n  @Prop() itemLabel: string = 'items';\n  /** Visible page-size control label. */\n  @Prop() pageSizeLabel: string = 'Items';\n  /** Accessible page-size control label. Defaults to “{pageSizeLabel} per page”. */\n  @Prop() pageSizeAriaLabel: string | undefined;\n  /** Accessible name for the pagination navigation region. */\n  @Prop() label: string = 'Pagination';\n  /** Prevent interaction while the owner replaces the current data page. */\n  @Prop() loading: boolean = false;\n\n  /** Emits the complete next controlled state after a page or page-size request. */\n  @Event() dsChange!: EventEmitter<PaginationChangeDetail>;\n\n  @State() private tableCompact = false;\n\n  private readonly pageSizeControlId = `ds-pagination-${++paginationId}-page-size`;\n  private tableCompactDisconnect: (() => void) | undefined;\n  private hasLoaded = false;\n\n  componentDidLoad(): void {\n    this.hasLoaded = true;\n    this.syncTableCompactObserver();\n  }\n\n  connectedCallback(): void {\n    if (this.hasLoaded) this.syncTableCompactObserver();\n  }\n\n  disconnectedCallback(): void {\n    this.tableCompactDisconnect?.();\n    this.tableCompactDisconnect = undefined;\n  }\n\n  private syncTableCompactObserver(): void {\n    this.tableCompactDisconnect?.();\n    this.tableCompactDisconnect = observeTableCaptionCompact(this.el, compact => {\n      if (this.tableCompact !== compact) this.tableCompact = compact;\n    });\n  }\n\n  private requestPage(pageIndex: number): void {\n    const state = this.resolvedState;\n    if (this.loading || pageIndex === state.pageIndex || pageIndex < 0 || pageIndex >= state.totalPages) {\n      return;\n    }\n    this.dsChange.emit({\n      pageIndex,\n      pageSize: state.pageSize,\n      pageSizeMode: state.pageSizeMode,\n      totalItems: state.totalItems,\n      pageSizeOptions: state.pageSizeOptions,\n      fitToPage: this.fitToPage,\n      fitToPageInactive: this.fitToPageInactive,\n      fitPageSize: this.resolvedFitPageSize,\n      fitPageSizeLabel: this.fitPageSizeLabel,\n      fitPageSizeTriggerLabel: this.fitPageSizeTriggerLabel,\n      itemLabel: this.itemLabel,\n      pageSizeLabel: this.pageSizeLabel,\n      ariaLabel: this.label,\n      previousPageIndex: state.pageIndex,\n      previousPageSize: state.pageSize,\n      previousPageSizeMode: state.pageSizeMode,\n      reason: 'page',\n    });\n  }\n\n  private requestPageSize(value: string | string[]): void {\n    if (\n      this.loading ||\n      typeof value !== 'string' ||\n      (value === 'fit' && this.fitToPageInactive)\n    ) return;\n    const state = this.resolvedState;\n    const nextMode: PaginationPageSizeMode = value === 'fit' ? 'fit' : 'fixed';\n    const pageSize = nextMode === 'fit' ? this.resolvedFitPageSize : Number(value);\n    if (!pageSize || (pageSize === state.pageSize && nextMode === state.pageSizeMode)) return;\n    this.dsChange.emit({\n      pageIndex: 0,\n      pageSize: Math.trunc(pageSize),\n      pageSizeMode: nextMode,\n      totalItems: state.totalItems,\n      pageSizeOptions: state.pageSizeOptions,\n      fitToPage: this.fitToPage,\n      fitToPageInactive: this.fitToPageInactive,\n      fitPageSize: this.resolvedFitPageSize,\n      fitPageSizeLabel: this.fitPageSizeLabel,\n      fitPageSizeTriggerLabel: this.fitPageSizeTriggerLabel,\n      itemLabel: this.itemLabel,\n      pageSizeLabel: this.pageSizeLabel,\n      ariaLabel: this.label,\n      previousPageIndex: state.pageIndex,\n      previousPageSize: state.pageSize,\n      previousPageSizeMode: state.pageSizeMode,\n      reason: 'page-size',\n    });\n  }\n\n  private handleKeyDown(event: KeyboardEvent): void {\n    if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) {\n      return;\n    }\n    const fromChoiceControl = event.composedPath().some(node =>\n      node instanceof HTMLElement &&\n      (node.tagName === 'DS-SELECT' || ['INPUT', 'SELECT', 'TEXTAREA'].includes(node.tagName)),\n    );\n    if (fromChoiceControl || (event.key !== 'ArrowLeft' && event.key !== 'ArrowRight')) return;\n    const state = this.resolvedState;\n    const pageIndex = event.key === 'ArrowLeft' ? state.pageIndex - 1 : state.pageIndex + 1;\n    if (this.loading || pageIndex < 0 || pageIndex >= state.totalPages) return;\n    event.preventDefault();\n    this.requestPage(pageIndex);\n  }\n\n  private get resolvedFitPageSize(): number | undefined {\n    return Number.isFinite(this.fitPageSize) && Number(this.fitPageSize) > 0\n      ? Math.trunc(Number(this.fitPageSize))\n      : undefined;\n  }\n\n  private get resolvedState() {\n    return resolvePaginationState({\n      pageIndex: this.pageIndex,\n      pageSize: this.pageSize,\n      pageSizeMode: this.pageSizeMode,\n      totalItems: this.totalItems,\n      pageSizeOptions: this.pageSizeOptions,\n    });\n  }\n\n  render() {\n    const state = this.resolvedState;\n    const atStart = state.pageIndex === 0;\n    const atEnd = state.pageIndex === state.totalPages - 1;\n    const visibleItems = state.totalItems === 0 ? 0 : state.lastItem - state.firstItem + 1;\n    const total = `${visibleItems} of ${state.totalItems}`;\n    const page = `${state.pageIndex + 1} of ${state.totalPages}`;\n    const announcedRange = `${state.firstItem}–${state.lastItem} of ${state.totalItems}`;\n    const announcedPage = `Page ${state.pageIndex + 1} of ${state.totalPages}`;\n    const pageSizeAriaLabel = this.pageSizeAriaLabel ?? `${this.pageSizeLabel} per page`;\n    const options: Array<{ label: string; value: string; isInactive?: boolean }> =\n      state.pageSizeOptions.map(value => ({ label: String(value), value: String(value) }));\n    if (this.fitToPage) {\n      options.push({\n        label: this.fitPageSizeLabel,\n        value: 'fit',\n        isInactive: this.fitToPageInactive || this.resolvedFitPageSize === undefined,\n      });\n    }\n\n    return (\n      <Host>\n        <nav\n          class={{\n            pagination: true,\n            'pagination--table-compact': this.tableCompact,\n          }}\n          aria-label={this.label}\n          aria-busy={this.loading ? 'true' : undefined}\n          onKeyDown={event => this.handleKeyDown(event)}\n        >\n          <div class=\"pagination__page-size\">\n            <ds-text\n              class=\"pagination__label\"\n              as=\"span\"\n              variant=\"text-body-medium\"\n              color=\"secondary\"\n              aria-hidden=\"true\"\n            >\n              {this.pageSizeLabel}:\n            </ds-text>\n            <span id={`${this.pageSizeControlId}-label`} class=\"ds-visually-hidden\">\n              {pageSizeAriaLabel}\n            </span>\n            <ds-select\n              class=\"pagination__page-size-select\"\n              size=\"md\"\n              inputId={this.pageSizeControlId}\n              ariaLabelledby={`${this.pageSizeControlId}-label`}\n              options={options}\n              value={state.pageSizeMode === 'fit' ? 'fit' : String(state.pageSize)}\n              triggerLabel={state.pageSizeMode === 'fit' ? this.fitPageSizeTriggerLabel : undefined}\n              indicator=\"up-down\"\n              allowClear={false}\n              activeFill={false}\n              hasBorder={false}\n              isInactive={this.loading}\n              onDsChange={event => {\n                event.stopPropagation();\n                this.requestPageSize(event.detail);\n              }}\n            />\n            <ds-text\n              class=\"pagination__total\"\n              as=\"span\"\n              variant=\"text-body-medium\"\n              color=\"secondary\"\n              fontFeature=\"tabular-nums\"\n            >\n              {total}\n            </ds-text>\n          </div>\n          <ds-divider\n            class=\"pagination__divider\"\n            orientation=\"vertical\"\n            length=\"var(--dimension-size-250)\"\n          />\n          <div class=\"pagination__navigation\">\n            <ds-button-unfilled\n              class=\"pagination__boundary\"\n              variant=\"icon\"\n              size=\"md\"\n              icon=\"ChevronLeftDouble\"\n              ariaLabel=\"First page\"\n              hasBorder={false}\n              isInactive={this.loading || atStart}\n              onDsClick={() => this.requestPage(0)}\n            />\n            <ds-button-unfilled\n              variant=\"icon\"\n              size=\"md\"\n              icon=\"ChevronLeft\"\n              ariaLabel=\"Previous page\"\n              hasBorder={false}\n              isInactive={this.loading || atStart}\n              onDsClick={() => this.requestPage(state.pageIndex - 1)}\n            />\n            <ds-text\n              class=\"pagination__page\"\n              as=\"span\"\n              variant=\"text-body-medium\"\n              color=\"secondary\"\n              fontFeature=\"tabular-nums\"\n            >\n              {page}\n            </ds-text>\n            <ds-button-unfilled\n              variant=\"icon\"\n              size=\"md\"\n              icon=\"ChevronRight\"\n              ariaLabel=\"Next page\"\n              hasBorder={false}\n              isInactive={this.loading || atEnd}\n              onDsClick={() => this.requestPage(state.pageIndex + 1)}\n            />\n            <ds-button-unfilled\n              class=\"pagination__boundary\"\n              variant=\"icon\"\n              size=\"md\"\n              icon=\"ChevronRightDouble\"\n              ariaLabel=\"Last page\"\n              hasBorder={false}\n              isInactive={this.loading || atEnd}\n              onDsClick={() => this.requestPage(state.totalPages - 1)}\n            />\n          </div>\n          <span class=\"ds-visually-hidden\" role=\"status\" aria-live=\"polite\" aria-atomic=\"true\">\n            {announcedRange} {this.itemLabel}. {announcedPage}.\n          </span>\n        </nav>\n      </Host>\n    );\n  }\n}\n",
+      "content": "import { Component, Element, Event, EventEmitter, h, Host, Prop, State } from '@stencil/core';\nimport { observeTableCaptionCompact } from '../../utils/table-caption-compact';\nimport { resolvePaginationState } from './pagination-model';\nimport type {\n  PaginationChangeDetail,\n  PaginationPageSizeMode,\n} from './pagination-types';\n\nlet paginationId = 0;\n\n@Component({\n  tag: 'ds-pagination',\n  styleUrl: 'Pagination.css',\n  scoped: true,\n})\nexport class Pagination {\n  @Element() el!: HTMLElement;\n\n  /** Controlled zero-based page index. */\n  @Prop() pageIndex: number = 0;\n  /** Controlled number of top-level items on a full page. */\n  @Prop() pageSize: number = 25;\n  /** Whether pageSize is a fixed choice or a measured Fit snapshot. */\n  @Prop() pageSizeMode: PaginationPageSizeMode = 'fixed';\n  /** Controlled total number of top-level items across every page. */\n  @Prop() totalItems: number = 0;\n  /** Available page sizes. Assign arrays through JavaScript. */\n  @Prop() pageSizeOptions: number[] = [25, 50, 100, 200];\n  /** Include the Fit to page choice. */\n  @Prop() fitToPage: boolean = false;\n  /** Keep the Fit to page choice visible but unavailable. */\n  @Prop() fitToPageInactive: boolean = false;\n  /** Effective whole-item capacity to request when Fit is selected. */\n  @Prop() fitPageSize: number | undefined;\n  /** Full choice-list label for Fit. */\n  @Prop() fitPageSizeLabel: string = 'Fit to page';\n  /** Compact closed-trigger label while Fit is selected. */\n  @Prop() fitPageSizeTriggerLabel: string = 'Fit';\n  /** Localized plural noun used by assistive range announcements. */\n  @Prop() itemLabel: string = 'items';\n  /** Visible page-size control label. */\n  @Prop() pageSizeLabel: string = 'Items';\n  /** Accessible page-size control label. Defaults to “{pageSizeLabel} per page”. */\n  @Prop() pageSizeAriaLabel: string | undefined;\n  /** Accessible name for the pagination navigation region. */\n  @Prop() label: string = 'Pagination';\n  /** Include direct first-page and last-page controls. */\n  @Prop() showFirstLastButtons: boolean = false;\n  /** Prevent interaction while the owner replaces the current data page. */\n  @Prop() loading: boolean = false;\n\n  /** Emits the complete next controlled state after a page or page-size request. */\n  @Event() dsChange!: EventEmitter<PaginationChangeDetail>;\n\n  @State() private tableCompact = false;\n\n  private readonly pageSizeControlId = `ds-pagination-${++paginationId}-page-size`;\n  private tableCompactDisconnect: (() => void) | undefined;\n  private hasLoaded = false;\n\n  componentDidLoad(): void {\n    this.hasLoaded = true;\n    this.syncTableCompactObserver();\n  }\n\n  connectedCallback(): void {\n    if (this.hasLoaded) this.syncTableCompactObserver();\n  }\n\n  disconnectedCallback(): void {\n    this.tableCompactDisconnect?.();\n    this.tableCompactDisconnect = undefined;\n  }\n\n  private syncTableCompactObserver(): void {\n    this.tableCompactDisconnect?.();\n    this.tableCompactDisconnect = observeTableCaptionCompact(this.el, compact => {\n      if (this.tableCompact !== compact) this.tableCompact = compact;\n    });\n  }\n\n  private requestPage(pageIndex: number): void {\n    const state = this.resolvedState;\n    if (this.loading || pageIndex === state.pageIndex || pageIndex < 0 || pageIndex >= state.totalPages) {\n      return;\n    }\n    this.dsChange.emit({\n      pageIndex,\n      pageSize: state.pageSize,\n      pageSizeMode: state.pageSizeMode,\n      totalItems: state.totalItems,\n      pageSizeOptions: state.pageSizeOptions,\n      fitToPage: this.fitToPage,\n      fitToPageInactive: this.fitToPageInactive,\n      fitPageSize: this.resolvedFitPageSize,\n      fitPageSizeLabel: this.fitPageSizeLabel,\n      fitPageSizeTriggerLabel: this.fitPageSizeTriggerLabel,\n      itemLabel: this.itemLabel,\n      pageSizeLabel: this.pageSizeLabel,\n      ariaLabel: this.label,\n      showFirstLastButtons: this.showFirstLastButtons,\n      previousPageIndex: state.pageIndex,\n      previousPageSize: state.pageSize,\n      previousPageSizeMode: state.pageSizeMode,\n      reason: 'page',\n    });\n  }\n\n  private requestPageSize(value: string | string[]): void {\n    if (\n      this.loading ||\n      typeof value !== 'string' ||\n      (value === 'fit' && this.fitToPageInactive)\n    ) return;\n    const state = this.resolvedState;\n    const nextMode: PaginationPageSizeMode = value === 'fit' ? 'fit' : 'fixed';\n    const pageSize = nextMode === 'fit' ? this.resolvedFitPageSize : Number(value);\n    if (!pageSize || (pageSize === state.pageSize && nextMode === state.pageSizeMode)) return;\n    this.dsChange.emit({\n      pageIndex: 0,\n      pageSize: Math.trunc(pageSize),\n      pageSizeMode: nextMode,\n      totalItems: state.totalItems,\n      pageSizeOptions: state.pageSizeOptions,\n      fitToPage: this.fitToPage,\n      fitToPageInactive: this.fitToPageInactive,\n      fitPageSize: this.resolvedFitPageSize,\n      fitPageSizeLabel: this.fitPageSizeLabel,\n      fitPageSizeTriggerLabel: this.fitPageSizeTriggerLabel,\n      itemLabel: this.itemLabel,\n      pageSizeLabel: this.pageSizeLabel,\n      ariaLabel: this.label,\n      showFirstLastButtons: this.showFirstLastButtons,\n      previousPageIndex: state.pageIndex,\n      previousPageSize: state.pageSize,\n      previousPageSizeMode: state.pageSizeMode,\n      reason: 'page-size',\n    });\n  }\n\n  private handleKeyDown(event: KeyboardEvent): void {\n    if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) {\n      return;\n    }\n    const fromChoiceControl = event.composedPath().some(node =>\n      node instanceof HTMLElement &&\n      (node.tagName === 'DS-SELECT' || ['INPUT', 'SELECT', 'TEXTAREA'].includes(node.tagName)),\n    );\n    if (fromChoiceControl || (event.key !== 'ArrowLeft' && event.key !== 'ArrowRight')) return;\n    const state = this.resolvedState;\n    const pageIndex = event.key === 'ArrowLeft' ? state.pageIndex - 1 : state.pageIndex + 1;\n    if (this.loading || pageIndex < 0 || pageIndex >= state.totalPages) return;\n    event.preventDefault();\n    this.requestPage(pageIndex);\n  }\n\n  private get resolvedFitPageSize(): number | undefined {\n    return Number.isFinite(this.fitPageSize) && Number(this.fitPageSize) > 0\n      ? Math.trunc(Number(this.fitPageSize))\n      : undefined;\n  }\n\n  private get resolvedState() {\n    return resolvePaginationState({\n      pageIndex: this.pageIndex,\n      pageSize: this.pageSize,\n      pageSizeMode: this.pageSizeMode,\n      totalItems: this.totalItems,\n      pageSizeOptions: this.pageSizeOptions,\n    });\n  }\n\n  render() {\n    const state = this.resolvedState;\n    const atStart = state.pageIndex === 0;\n    const atEnd = state.pageIndex === state.totalPages - 1;\n    const visibleItems = state.totalItems === 0 ? 0 : state.lastItem - state.firstItem + 1;\n    const total = `${visibleItems} of ${state.totalItems}`;\n    const page = `${state.pageIndex + 1} of ${state.totalPages}`;\n    const announcedRange = `${state.firstItem}–${state.lastItem} of ${state.totalItems}`;\n    const announcedPage = `Page ${state.pageIndex + 1} of ${state.totalPages}`;\n    const pageSizeAriaLabel = this.pageSizeAriaLabel ?? `${this.pageSizeLabel} per page`;\n    const options: Array<{ label: string; value: string; isInactive?: boolean }> =\n      state.pageSizeOptions.map(value => ({ label: String(value), value: String(value) }));\n    if (this.fitToPage) {\n      options.push({\n        label: this.fitPageSizeLabel,\n        value: 'fit',\n        isInactive: this.fitToPageInactive || this.resolvedFitPageSize === undefined,\n      });\n    }\n\n    return (\n      <Host>\n        <nav\n          class={{\n            pagination: true,\n            'pagination--table-compact': this.tableCompact,\n          }}\n          aria-label={this.label}\n          aria-busy={this.loading ? 'true' : undefined}\n          onKeyDown={event => this.handleKeyDown(event)}\n        >\n          <div class=\"pagination__page-size\">\n            <ds-text\n              class=\"pagination__label\"\n              as=\"span\"\n              variant=\"text-body-medium\"\n              color=\"secondary\"\n              aria-hidden=\"true\"\n            >\n              {this.pageSizeLabel}:\n            </ds-text>\n            <span id={`${this.pageSizeControlId}-label`} class=\"ds-visually-hidden\">\n              {pageSizeAriaLabel}\n            </span>\n            <ds-select\n              class=\"pagination__page-size-select\"\n              size=\"md\"\n              inputId={this.pageSizeControlId}\n              ariaLabelledby={`${this.pageSizeControlId}-label`}\n              options={options}\n              value={state.pageSizeMode === 'fit' ? 'fit' : String(state.pageSize)}\n              triggerLabel={state.pageSizeMode === 'fit' ? this.fitPageSizeTriggerLabel : undefined}\n              indicator=\"up-down\"\n              allowClear={false}\n              activeFill={false}\n              hasBorder={false}\n              isInactive={this.loading}\n              onDsChange={event => {\n                event.stopPropagation();\n                this.requestPageSize(event.detail);\n              }}\n            />\n            <ds-text\n              class=\"pagination__total\"\n              as=\"span\"\n              variant=\"text-body-medium\"\n              color=\"secondary\"\n              fontFeature=\"tabular-nums\"\n            >\n              {total}\n            </ds-text>\n          </div>\n          <ds-divider\n            class=\"pagination__divider\"\n            orientation=\"vertical\"\n            length=\"var(--dimension-size-250)\"\n          />\n          <div class=\"pagination__navigation\">\n            {this.showFirstLastButtons ? (\n              <ds-button-unfilled\n                class=\"pagination__boundary\"\n                variant=\"icon\"\n                size=\"md\"\n                icon=\"ChevronLeftDouble\"\n                ariaLabel=\"First page\"\n                hasBorder={false}\n                isInactive={this.loading || atStart}\n                onDsClick={() => this.requestPage(0)}\n              />\n            ) : null}\n            <ds-button-unfilled\n              variant=\"icon\"\n              size=\"md\"\n              icon=\"ChevronLeft\"\n              ariaLabel=\"Previous page\"\n              hasBorder={false}\n              isInactive={this.loading || atStart}\n              onDsClick={() => this.requestPage(state.pageIndex - 1)}\n            />\n            <ds-text\n              class=\"pagination__page\"\n              as=\"span\"\n              variant=\"text-body-medium\"\n              color=\"secondary\"\n              fontFeature=\"tabular-nums\"\n            >\n              {page}\n            </ds-text>\n            <ds-button-unfilled\n              variant=\"icon\"\n              size=\"md\"\n              icon=\"ChevronRight\"\n              ariaLabel=\"Next page\"\n              hasBorder={false}\n              isInactive={this.loading || atEnd}\n              onDsClick={() => this.requestPage(state.pageIndex + 1)}\n            />\n            {this.showFirstLastButtons ? (\n              <ds-button-unfilled\n                class=\"pagination__boundary\"\n                variant=\"icon\"\n                size=\"md\"\n                icon=\"ChevronRightDouble\"\n                ariaLabel=\"Last page\"\n                hasBorder={false}\n                isInactive={this.loading || atEnd}\n                onDsClick={() => this.requestPage(state.totalPages - 1)}\n              />\n            ) : null}\n          </div>\n          <span class=\"ds-visually-hidden\" role=\"status\" aria-live=\"polite\" aria-atomic=\"true\">\n            {announcedRange} {this.itemLabel}. {announcedPage}.\n          </span>\n        </nav>\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     },
     {
@@ -419,7 +440,7 @@
     },
     {
       "path": "src/wc/components/Pagination/pagination-types.ts",
-      "content": "export type PaginationChangeReason = 'page' | 'page-size' | 'fit';\nexport type PaginationPageSizeMode = 'fixed' | 'fit';\n\n/** Controlled pagination state shared by Pagination and pagination-aware consumers. */\nexport interface PaginationState {\n  /** Zero-based page index. */\n  pageIndex: number;\n  /** Number of top-level items on a full page. */\n  pageSize: number;\n  /** Whether pageSize is a chosen fixed value or a measured Fit snapshot. */\n  pageSizeMode?: PaginationPageSizeMode;\n  /** Total number of top-level items across every page. */\n  totalItems: number;\n  /** Available page sizes. Defaults to 25, 50, 100, and 200. */\n  pageSizeOptions?: number[];\n  /** Include a Fit to page option. The owner supplies the effective fitted size. */\n  fitToPage?: boolean;\n  /** Keep the Fit to page option visible but unavailable for the current data shape. */\n  fitToPageInactive?: boolean;\n  /** Effective page size proposed when Fit to page is selected. */\n  fitPageSize?: number;\n  /** Full option label for Fit in the open choice list. */\n  fitPageSizeLabel?: string;\n  /** Compact trigger label while Fit is selected. */\n  fitPageSizeTriggerLabel?: string;\n  /** Localized plural noun used by assistive range announcements. */\n  itemLabel?: string;\n  /** Visible label for the page-size selector. */\n  pageSizeLabel?: string;\n  /** Accessible name for the pagination navigation region. */\n  ariaLabel?: string;\n}\n\n/** Complete next controlled state emitted for a page or page-size request. */\nexport interface PaginationChangeDetail extends PaginationState {\n  previousPageIndex: number;\n  previousPageSize: number;\n  previousPageSizeMode: PaginationPageSizeMode;\n  reason: PaginationChangeReason;\n}\n",
+      "content": "export type PaginationChangeReason = 'page' | 'page-size' | 'fit';\nexport type PaginationPageSizeMode = 'fixed' | 'fit';\n\n/** Controlled pagination state shared by Pagination and pagination-aware consumers. */\nexport interface PaginationState {\n  /** Zero-based page index. */\n  pageIndex: number;\n  /** Number of top-level items on a full page. */\n  pageSize: number;\n  /** Whether pageSize is a chosen fixed value or a measured Fit snapshot. */\n  pageSizeMode?: PaginationPageSizeMode;\n  /** Total number of top-level items across every page. */\n  totalItems: number;\n  /** Available page sizes. Defaults to 25, 50, 100, and 200. */\n  pageSizeOptions?: number[];\n  /** Include a Fit to page option. The owner supplies the effective fitted size. */\n  fitToPage?: boolean;\n  /** Keep the Fit to page option visible but unavailable for the current data shape. */\n  fitToPageInactive?: boolean;\n  /** Effective page size proposed when Fit to page is selected. */\n  fitPageSize?: number;\n  /** Full option label for Fit in the open choice list. */\n  fitPageSizeLabel?: string;\n  /** Compact trigger label while Fit is selected. */\n  fitPageSizeTriggerLabel?: string;\n  /** Localized plural noun used by assistive range announcements. */\n  itemLabel?: string;\n  /** Visible label for the page-size selector. */\n  pageSizeLabel?: string;\n  /** Accessible name for the pagination navigation region. */\n  ariaLabel?: string;\n  /** Include direct first-page and last-page controls around Previous and Next. */\n  showFirstLastButtons?: boolean;\n}\n\n/** Complete next controlled state emitted for a page or page-size request. */\nexport interface PaginationChangeDetail extends PaginationState {\n  previousPageIndex: number;\n  previousPageSize: number;\n  previousPageSizeMode: PaginationPageSizeMode;\n  reason: PaginationChangeReason;\n}\n",
       "type": "registry:ui"
     }
   ]

package/dist/mcp-data/registry/registry.json

@@ -6066,7 +6066,7 @@
     {
       "name": "pagination",
       "title": "Pagination",
-      "description": "Controlled fixed or fitted page-size, compact range, and first/previous/next/last navigation for application-owned data windows.",
+      "description": "Controlled fixed or fitted page-size, compact range, adjacent-page navigation, and optional first/last controls for application-owned data windows.",
       "type": "registry:ui",
       "meta": {
         "library": "@ds-mo/ui",
@@ -6077,14 +6077,15 @@
         "intent": {
           "audience": "general",
           "status": "stable",
-          "summary": "Controlled fixed or fitted page-size, compact range, and first/previous/next/last navigation for application-owned data windows.",
+          "summary": "Controlled fixed or fitted page-size, compact range, adjacent-page navigation, and optional first/last controls for application-owned data windows.",
           "useWhen": [
             "A result set is divided into discrete pages and the application owns fetching or slicing each page.",
-            "A table or list needs a compact page-size selector, result range, and boundary-aware navigation."
+            "A table or list needs a compact page-size selector, result range, and boundary-aware navigation.",
+            "Direct first-page and last-page navigation is useful enough to opt into alongside the default Previous and Next controls."
           ],
           "avoidWhen": [
             "More results append to one continuous list; use the owning component's incremental-loading behavior instead.",
-            "Only previous and next navigation is meaningful and the total result count is unknown."
+            "The total result count is unknown; use an incremental-loading pattern instead."
           ],
           "commonlyComposedWith": [
             "component:ds-table",
@@ -6095,18 +6096,20 @@
             "The component renders a named navigation region, gives its compact page-size noun a complete accessible label, and gives every icon-only boundary control an explicit page action name.",
             "The visible page-size cluster states the localized noun, selected size, and current-page count of total, for example Rows: [25] 25 of 500. The page position uses compact ‘of’ phrasing, for example 1 of 20. A polite atomic status update retains the complete current range and ‘Page’ phrasing with the localized item noun.",
             "Left and Right Arrow request the adjacent page while focus is within pagination navigation controls. The page-size combobox retains its own arrow-key behavior.",
-            "Inactive boundary controls and every control during loading remain non-interactive while retaining their accessible names."
+            "Inactive boundary controls and every control during loading remain non-interactive while retaining their accessible names.",
+            "showFirstLastButtons adds explicitly named First page and Last page controls; Previous and Next remain present in either mode."
           ],
           "states": [
             "pageIndex, numeric effective pageSize, pageSizeMode, totalItems, and pageSizeOptions are controlled inputs. dsChange reports the complete next pagination state, previous index, size, and mode, and whether the request changed the page, page size, or fitted capacity; it never mutates controlled inputs.",
             "Page-size changes request the first page. Out-of-range page indexes and invalid numeric inputs normalize only for presentation; the owner remains authoritative.",
             "Zero results display 0–0 of 0 and Page 1 of 1. A partial final page caps the visible range at totalItems.",
             "loading preserves the full pagination surface, applies aria-busy to the navigation region, and prevents page or page-size requests.",
-            "fitToPage appends a Fit to page choice. fitPageSize supplies its effective whole-item capacity; the closed trigger says Fit while the range continues to expose the resulting count. fitToPageInactive keeps that choice visible but unavailable when fitting is not meaningful for the current data shape. Pagination does not measure layouts itself."
+            "fitToPage appends a Fit to page choice. fitPageSize supplies its effective whole-item capacity; the closed trigger says Fit while the range continues to expose the resulting count. fitToPageInactive keeps that choice visible but unavailable when fitting is not meaningful for the current data shape. Pagination does not measure layouts itself.",
+            "showFirstLastButtons defaults to false. Enable it when direct jumps to both result boundaries materially help the workflow."
           ],
           "responsiveBehavior": [
-            "The full-width controls remain on one line with noun, selected size, current-page count of total, a vertical divider, page position, and first, previous, next, and last navigation.",
-            "Inside a ds-table container narrower than 900px, pagination hides the visible current-page count and first/last boundary controls while retaining the page-size noun and selector plus previous, page position, and next. The complete current range remains available to assistive technology."
+            "The full-width controls remain on one line with noun, selected size, current-page count of total, a vertical divider, page position, Previous and Next, plus optional First and Last navigation.",
+            "Inside a ds-table container narrower than 900px, pagination hides the visible current-page count and any opted-in first/last controls while retaining the page-size noun and selector plus Previous, page position, and Next. The complete current range remains available to assistive technology."
           ],
           "frameworkCaveats": {
             "customElements": [
@@ -6183,6 +6186,10 @@
             "type": "number[]",
             "required": false
           },
+          "showFirstLastButtons": {
+            "type": "boolean",
+            "required": false
+          },
           "totalItems": {
             "type": "number",
             "required": false