@openreachtech/furo-vue 1.3.1

package/lib/components/molecules/FuroPagination/FuroPagination.vue

@@ -0,0 +1,246 @@
+<script>
+import {
+  defineComponent,
+} from 'vue'
+
+import {
+  Pagination as RekaPagination,
+} from 'reka-ui/namespaced'
+
+import FuroIcon from '../../atoms/FuroIcon/FuroIcon.vue'
+import FuroPaginationContext from './FuroPaginationContext.js'
+
+export default defineComponent({
+  name: 'FuroPagination',
+
+  components: {
+    FuroIcon,
+    PaginationRoot: RekaPagination['Root'],
+    PaginationPrev: RekaPagination['Prev'],
+    PaginationNext: RekaPagination['Next'],
+    PaginationRange: RekaPagination['List'],
+    PaginationPage: RekaPagination['ListItem'],
+    PaginationEllipsis: RekaPagination['Ellipsis'],
+  },
+
+  inheritAttrs: false,
+
+  props: {
+    parcel: {
+      /** @type {import('vue').PropType<import('./FuroPaginationContext.js').Props['parcel']>} */
+      type: [
+        Object,
+        null,
+      ],
+      default: null,
+    },
+  },
+
+  slots: /** @type {import('./FuroPaginationContext.js').FuroPaginationSlots} */ (Object),
+  emits: FuroPaginationContext.EMIT_EVENT_HASH,
+
+  /** @type {import('./FuroPaginationContext.js').FuroPaginationSetup} */
+  setup (
+    props,
+    componentContext
+  ) {
+    const context = FuroPaginationContext.create({
+      props,
+      componentContext,
+    })
+
+    return {
+      context,
+    }
+  },
+})
+</script>
+
+<template>
+  <PaginationRoot
+    :class="context.extractRootClassNames()"
+    :page="context.extractPageValue()"
+    :items-per-page="context.extractLimit()"
+    :total="context.extractTotalRecords()"
+    :sibling-count="context.extractSiblingCount()"
+    :show-edges="context.shouldShowEdges()"
+    :disabled="context.isDisabled()"
+    v-bind="$attrs"
+    @update:page="context.onPageChange({
+      page: $event,
+    })"
+  >
+    <PaginationPrev class="previous">
+      <slot name="previous">
+        <FuroIcon
+          name="ph:caret-left"
+          class="icon"
+        />
+      </slot>
+    </PaginationPrev>
+
+    <PaginationRange
+      v-slot="{ items: pages }"
+      class="pages"
+    >
+      <template
+        v-for="(entry, index) in pages"
+        :key="index"
+      >
+        <PaginationPage
+          v-if="context.isPageEntry({ entry })"
+          class="page"
+          :value="context.extractEntryPage({ entry })"
+          :as-child="context.hasPageSlot()"
+        >
+          <slot
+            name="page"
+            :page="context.extractEntryPage({ entry })"
+          >
+            {{ context.extractEntryPage({ entry }) }}
+          </slot>
+        </PaginationPage>
+
+        <PaginationEllipsis
+          v-else
+          class="ellipsis"
+        >
+          <slot name="ellipsis">
+            <FuroIcon
+              name="ph:dots-three"
+              class="icon"
+            />
+          </slot>
+        </PaginationEllipsis>
+      </template>
+    </PaginationRange>
+
+    <PaginationNext class="next">
+      <slot name="next">
+        <FuroIcon
+          name="ph:caret-right"
+          class="icon"
+        />
+      </slot>
+    </PaginationNext>
+  </PaginationRoot>
+</template>
+
+<style>
+@layer furo {
+  .unit-pagination {
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    gap: var(--size-space-tiny);
+  }
+
+  .unit-pagination.disabled {
+    opacity: 0.5;
+    pointer-events: none;
+  }
+
+  .unit-pagination > .pages {
+    display: flex;
+    align-items: center;
+    gap: var(--size-space-tiny);
+  }
+
+  .unit-pagination .page {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+
+    min-width: 2rem;
+    height: 2rem;
+
+    border: none;
+    border-radius: var(--size-border-radius-small);
+
+    padding-block: 0;
+    padding-inline: 0.5rem;
+
+    background-color: transparent;
+    color: var(--color-foreground);
+    font: var(--font-label-small);
+    font-variant-numeric: tabular-nums;
+    text-decoration: none;
+
+    cursor: pointer;
+
+    appearance: none;
+
+    transition-duration: var(--transition-timer);
+    transition-property: background-color, color;
+  }
+
+  .unit-pagination .page:hover {
+    background-color: var(--color-accent);
+    color: var(--color-accent-foreground);
+  }
+
+  .unit-pagination .page[data-selected] {
+    background-color: var(--color-primary);
+    color: var(--color-primary-foreground);
+  }
+
+  .unit-pagination .page:focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 0.125rem var(--color-ring);
+  }
+
+  .unit-pagination :where(.previous, .next) {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+
+    width: 2rem;
+    height: 2rem;
+
+    border: none;
+    border-radius: var(--size-border-radius-small);
+
+    background-color: transparent;
+    color: var(--color-foreground);
+
+    cursor: pointer;
+
+    appearance: none;
+
+    transition-duration: var(--transition-timer);
+    transition-property: background-color, color;
+  }
+
+  .unit-pagination :where(.previous, .next):hover {
+    background-color: var(--color-accent);
+    color: var(--color-accent-foreground);
+  }
+
+  .unit-pagination :where(.previous, .next):focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 0.125rem var(--color-ring);
+  }
+
+  .unit-pagination :where(.previous, .next):disabled {
+    color: var(--color-muted-foreground);
+    cursor: not-allowed;
+    pointer-events: none;
+  }
+
+  .unit-pagination .ellipsis {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+
+    width: 2rem;
+    height: 2rem;
+
+    color: var(--color-muted-foreground);
+  }
+
+  .unit-pagination .icon {
+    width: 1rem;
+    height: 1rem;
+  }
+}
+</style>

package/lib/components/molecules/FuroPagination/FuroPaginationContext.js

@@ -0,0 +1,489 @@
+import {
+  ref,
+} from 'vue'
+
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+const DEFAULT_LIMIT = 20
+const DEFAULT_TOTAL_RECORDS = 0
+const DEFAULT_SIBLING_COUNT = 2
+
+/**
+ * Context class for FuroPagination organism.
+ *
+ * @extends {BaseFuroContext<null, Props, EmitEventName>}
+ */
+export default class FuroPaginationContext extends BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroPaginationContextParams} params - Parameters of this constructor.
+   */
+  constructor ({
+    props,
+    componentContext,
+
+    refHash,
+  }) {
+    super({
+      props,
+      componentContext,
+    })
+
+    this.refHash = refHash
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof FuroPaginationContext ? X : never} T, X
+   * @override
+   * @param {FuroPaginationContextFactoryParams} params - Parameters of this factory method.
+   * @returns {InstanceType<T>} An instance of this class.
+   * @this {T}
+   */
+  static create ({
+    props,
+    componentContext,
+
+    refHash = this.buildRefHash(),
+  }) {
+    return /** @type {InstanceType<T>} */ (
+      new this({
+        props,
+        componentContext,
+
+        refHash,
+      })
+    )
+  }
+
+  /**
+   * Build ref hash.
+   *
+   * @override
+   * @returns {FuroPaginationContextParams['refHash']}
+   */
+  static buildRefHash () {
+    return {
+      pageRef: ref(1),
+    }
+  }
+
+  /**
+   * Get emit event name.
+   *
+   * @override
+   * @returns {Readonly<{
+   *   PAGE_CHANGE: 'page:change'
+   *   UPDATE_PAGE: 'update:page'
+   * }>}
+   */
+  static get EMIT_EVENT_NAME () {
+    return {
+      PAGE_CHANGE: 'page:change',
+      UPDATE_PAGE: 'update:page',
+    }
+  }
+
+  /**
+   * Get emit options.
+   *
+   * @returns {{
+   *   'page:change': (payload: {
+   *     page: number
+   *     offset: number
+   *     limit: number
+   *   }) => void
+   *   'update:page': (page: number) => void
+   * }}
+   */
+  static get EMIT_EVENT_HASH () {
+    return {
+      [this.EMIT_EVENT_NAME.PAGE_CHANGE]: payload => {},
+      [this.EMIT_EVENT_NAME.UPDATE_PAGE]: payload => {},
+    }
+  }
+
+  /**
+   * get: Constructor of this class.
+   *
+   * @override
+   * @returns {typeof FuroPaginationContext}
+   */
+  get Ctor () {
+    return /** @type {typeof FuroPaginationContext} */ (
+      this.constructor
+    )
+  }
+
+  /**
+   * Get internal page ref (uncontrolled mode).
+   *
+   * @returns {import('vue').Ref<number>}
+   */
+  get pageRef () {
+    return this.refHash.pageRef
+  }
+
+  /**
+   * Parcel passed from parent via props.
+   *
+   * @override
+   * @returns {NonNullable<Props['parcel']>}
+   */
+  get parcel () {
+    return {
+      page: null,
+      offset: null,
+      limit: DEFAULT_LIMIT,
+      totalRecords: DEFAULT_TOTAL_RECORDS,
+      siblingCount: DEFAULT_SIBLING_COUNT,
+      showEdges: true,
+      disabled: false,
+      ...this.props.parcel,
+    }
+  }
+
+  /**
+   * Whether the current page is controlled via `parcel.page`.
+   *
+   * @returns {boolean}
+   */
+  isPageControlled () {
+    return (this.parcel?.page ?? null) !== null
+  }
+
+  /**
+   * Whether the current page is controlled via `parcel.offset`
+   * (offset/limit-style state, e.g. GraphQL pagination).
+   *
+   * @returns {boolean}
+   */
+  isOffsetControlled () {
+    return (this.parcel?.offset ?? null) !== null
+  }
+
+  /**
+   * Whether the page is controlled by the parent (via `page` or `offset`).
+   *
+   * @returns {boolean}
+   */
+  isControlled () {
+    return this.isPageControlled()
+      || this.isOffsetControlled()
+  }
+
+  /**
+   * Whether controlled `page` and `offset` are both set but disagree
+   * (i.e. `offset` is not the offset of `page`).
+   *
+   * @returns {boolean}
+   */
+  hasControlledConflict () {
+    if (!this.isPageControlled()) {
+      return false
+    }
+
+    if (!this.isOffsetControlled()) {
+      return false
+    }
+
+    const page = Number(this.parcel?.page)
+    const offset = Number(this.parcel?.offset)
+
+    return offset !== this.generateOffset({
+      page,
+    })
+  }
+
+  /**
+   * Fail when controlled `page` and `offset` disagree. Production keeps letting
+   * `page` win and ignores the mismatched `offset`.
+   *
+   * @returns {void}
+   * @throws {Error} When controlled `page` and `offset` disagree.
+   */
+  throwOnControlledConflict () {
+    if (process.env.NODE_ENV === 'production') {
+      return
+    }
+
+    if (!this.hasControlledConflict()) {
+      return
+    }
+
+    const page = this.parcel?.page
+    const offset = this.parcel?.offset
+
+    throw new Error(`[FuroPagination] \`parcel.page\` (${page}) and \`parcel.offset\` (${offset}) are both set but disagree. Provide only one to avoid divergence.`)
+  }
+
+  /**
+   * Whether the whole pagination control is disabled.
+   *
+   * @returns {boolean}
+   */
+  isDisabled () {
+    const disabledByParcel = Boolean(this.parcel?.disabled)
+    const disabledByAttrs = this.hasBooleanAttribute({ name: 'disabled' })
+
+    return disabledByParcel || disabledByAttrs
+  }
+
+  /**
+   * Whether the first and last pages stay pinned with ellipsis gaps.
+   *
+   * @returns {boolean}
+   */
+  shouldShowEdges () {
+    return this.parcel?.showEdges !== false
+  }
+
+  /**
+   * Resolve the current page for the root host element.
+   * `page` takes precedence over `offset` when both are provided.
+   *
+   * @returns {number}
+   */
+  extractPageValue () {
+    this.throwOnControlledConflict()
+
+    if (this.isPageControlled()) {
+      return Number(this.parcel?.page)
+    }
+
+    if (this.isOffsetControlled()) {
+      return this.generatePageFromOffset({
+        offset: Number(this.parcel?.offset),
+      })
+    }
+
+    return this.pageRef.value
+  }
+
+  /**
+   * Resolve the number of records per page.
+   *
+   * @returns {number}
+   */
+  extractLimit () {
+    return this.parcel?.limit
+      ?? DEFAULT_LIMIT
+  }
+
+  /**
+   * Resolve the total record count.
+   *
+   * @returns {number}
+   */
+  extractTotalRecords () {
+    return this.parcel?.totalRecords
+      ?? DEFAULT_TOTAL_RECORDS
+  }
+
+  /**
+   * Resolve how many sibling pages render on each side of the current page.
+   *
+   * @returns {number}
+   */
+  extractSiblingCount () {
+    return this.parcel?.siblingCount
+      ?? DEFAULT_SIBLING_COUNT
+  }
+
+  /**
+   * Extract root class names.
+   *
+   * @returns {Record<string, boolean>}
+   */
+  extractRootClassNames () {
+    return {
+      'unit-pagination': true,
+      disabled: this.isDisabled(),
+    }
+  }
+
+  /**
+   * Whether a rendered range entry is a page button (vs. an ellipsis gap).
+   *
+   * @param {{
+   *   entry: {
+   *     type: string
+   *     value?: number
+   *   }
+   * }} params
+   * @returns {boolean}
+   */
+  isPageEntry ({
+    entry,
+  }) {
+    return entry.type === 'page'
+  }
+
+  /**
+   * Extract the page number from a range entry.
+   *
+   * @param {{
+   *   entry: {
+   *     type: string
+   *     value?: number
+   *   }
+   * }} params
+   * @returns {number}
+   */
+  extractEntryPage ({
+    entry,
+  }) {
+    return entry.value
+      ?? 0
+  }
+
+  /**
+   * Whether the consumer provides a custom per-page slot (e.g. anchor links).
+   *
+   * @returns {boolean}
+   */
+  hasPageSlot () {
+    return Boolean(this.componentContext.slots?.page)
+  }
+
+  /**
+   * Generate the zero-based record offset for a page.
+   * Convenience for offset/limit-style data sources (e.g. GraphQL pagination).
+   *
+   * @param {{
+   *   page: number
+   * }} params
+   * @returns {number}
+   */
+  generateOffset ({
+    page,
+  }) {
+    return (page - 1) * this.extractLimit()
+  }
+
+  /**
+   * Generate the 1-based page that contains a given zero-based offset.
+   * Inverse of {@link generateOffset} for offset/limit-style state.
+   *
+   * @param {{
+   *   offset: number
+   * }} params
+   * @returns {number}
+   */
+  generatePageFromOffset ({
+    offset,
+  }) {
+    const limit = this.extractLimit()
+
+    if (limit <= 0) {
+      return 1
+    }
+
+    return Math.floor(offset / limit) + 1
+  }
+
+  /**
+   * Handle page updates from the root host element.
+   *
+   * @param {{
+   *   page: number
+   * }} params
+   */
+  onPageChange ({
+    page,
+  }) {
+    if (!this.isControlled()) {
+      this.pageRef.value = page
+    }
+
+    const limit = this.extractLimit()
+    const offset = this.generateOffset({
+      page,
+    })
+
+    this.emit(
+      this.EMIT_EVENT_NAME.UPDATE_PAGE,
+      page
+    )
+
+    this.emit(
+      this.EMIT_EVENT_NAME.PAGE_CHANGE,
+      {
+        page,
+        offset,
+        limit,
+      }
+    )
+  }
+}
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams & {
+ *   props: Props
+ *   componentContext: ComponentContext
+ *   refHash: {
+ *     pageRef: import('vue').Ref<number>
+ *   }
+ * }} FuroPaginationContextParams
+ */
+
+/**
+ * @typedef {Omit<FuroPaginationContextParams, 'refHash'> & {
+ *   refHash?: FuroPaginationContextParams['refHash']
+ * }} FuroPaginationContextFactoryParams
+ */
+
+/**
+ * @typedef {keyof typeof FuroPaginationContext.EMIT_EVENT_NAME} EmitEventName
+ */
+
+/**
+ * @typedef {import('vue').HTMLAttributes & {
+ *   parcel?: FuroPaginationParcel | null
+ * }} Props
+ */
+
+/**
+ * Closed-set Furo behavior for `<FuroPagination>`.
+ * JSON-serializable only. Not an open passthrough to the internal pagination primitive.
+ *
+ * @typedef {{
+ *   page?: number | null
+ *   offset?: number | null
+ *   limit?: number
+ *   totalRecords?: number
+ *   siblingCount?: number
+ *   showEdges?: boolean
+ *   disabled?: boolean
+ * }} FuroPaginationParcel
+ */
+
+/**
+ * @typedef {import('vue').SetupContext<FuroPaginationEmitHash, FuroPaginationSlots>} ComponentContext
+ */
+
+/**
+ * @typedef {typeof FuroPaginationContext.EMIT_EVENT_HASH} FuroPaginationEmitHash
+ */
+
+/**
+ * @typedef {import('vue').SlotsType<{
+ *   previous: {}
+ *   next: {}
+ *   ellipsis: {}
+ *   page: {
+ *     page: number
+ *   }
+ * }>} FuroPaginationSlots
+ */
+
+/**
+ * @typedef {(
+ *   props: Props,
+ *   componentContext: ComponentContext
+ * ) => {
+ *   context: FuroPaginationContext
+ * }} FuroPaginationSetup
+ */