@ticatec/topside-elements 1.0.0

package/dist/navigation/pagination/Pagination.svelte

@@ -0,0 +1,300 @@
+<script lang="ts">
+
+
+    import type {OnPageChange, Size} from "../../types";
+
+    interface Props {
+        pageCount: number;
+        pageNo?: number;
+        /** 形状：plain / round / circle */
+        variant?: 'plain' | 'round' | 'circle';
+        style?: string;
+        /** 尺寸档位；'large' 对应旧的 big */
+        size?: Size;
+        theme?: string;
+        onchange?: OnPageChange;
+    }
+
+    let {
+        pageCount = 0,
+        pageNo = $bindable(1),
+        variant = "round",
+        style = '',
+        size = 'medium',
+        theme,
+        onchange
+    }: Props = $props();
+
+    let pagination = $state<Array<number | null>>([]);
+
+    // Clamp the (bindable) pageNo into range without writing it back: the parent
+    // owns the value; user navigation goes through changePage() which updates the
+    // binding and then notifies via onchange.
+    let normalizedPageNo = $derived.by(() => {
+        if (pageCount <= 0) return 0;
+        if (pageNo < 1) return 1;
+        if (pageNo > pageCount) return pageCount;
+        return pageNo;
+    });
+
+    const buildPagination = () => {
+        if (pageCount <= 0) {
+            pagination = [];
+            return;
+        }
+        const current = normalizedPageNo;
+        const arr: Array<number | null> = [1];
+        if (pageCount < 6) {
+            for (let i = 2; i <= pageCount; i++) {
+                arr.push(i);
+            }
+        } else {
+            if (current == 1 || current == 2) {
+                arr.push(2, 3, null, pageCount);
+            } else if (current == pageCount || current == pageCount - 1) {
+                arr.push(null, pageCount - 2, pageCount - 1, pageCount);
+            } else if (current == 3) {
+                arr.push(2, 3, 4, null, pageCount);
+            } else if (current == pageCount - 2) {
+                arr.push(null, pageCount - 3, pageCount - 2, pageCount - 1, pageCount);
+            } else {
+                arr.push(null);
+                for (let i = current - 1; i <= current + 1; i++) {
+                    arr.push(i);
+                }
+                arr.push(null);
+                arr.push(pageCount);
+            }
+        }
+        pagination = arr;
+    }
+
+    // Single exit point for user navigation: update the two-way binding first, then notify.
+    const changePage = (value: number) => {
+        pageNo = value;
+        onchange?.(value);
+    };
+
+    const selectPage = (value: number) => () => {
+        if (normalizedPageNo != value) {
+            changePage(value);
+        }
+    };
+
+    const handlePageKeyDown = (value: number) => (e: KeyboardEvent) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            selectPage(value)();
+        }
+    };
+
+    let hasPrev = $derived(pageCount > 0 && normalizedPageNo > 1);
+    let hasNext = $derived(pageCount > 0 && normalizedPageNo < pageCount);
+
+    const goPrev = () => {
+        if (hasPrev) changePage(normalizedPageNo - 1);
+    };
+
+    const goNext = () => {
+        if (hasNext) changePage(normalizedPageNo + 1);
+    };
+
+    const handleNavKeyDown = (action: () => void) => (e: KeyboardEvent) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            action();
+        }
+    };
+
+    $effect(() => {
+        buildPagination();
+    });
+</script>
+
+<div class="topside-pagination-panel {variant}" class:big={size === 'large'} {style} data-theme={theme} role="navigation" aria-label="Pagination">
+    <div class="topside-page-nav" class:disabled={!hasPrev} role="button" tabindex={hasPrev ? 0 : -1}
+         aria-label="Previous page" aria-disabled={!hasPrev} onclick={goPrev} onkeydown={handleNavKeyDown(goPrev)}>
+        <i class="icon_google_keyboard_arrow_left" aria-hidden="true"></i>
+    </div>
+    {#each pagination as page}
+        {#if page}
+            <div class="topside-page-no" onclick={selectPage(page)} onkeydown={handlePageKeyDown(page)}
+                 role="button" tabindex="0" aria-current={page === normalizedPageNo ? 'page' : undefined}
+                 aria-label="Page {page}" class:selected={page === normalizedPageNo}>
+                <span>
+                    {page}
+                </span>
+            </div>
+        {:else}
+            <div class="topside-page-gap">
+                <span>...</span>
+            </div>
+        {/if}
+    {/each}
+    <div class="topside-page-nav" class:disabled={!hasNext} role="button" tabindex={hasNext ? 0 : -1}
+         aria-label="Next page" aria-disabled={!hasNext} onclick={goNext} onkeydown={handleNavKeyDown(goNext)}>
+        <i class="icon_google_keyboard_arrow_right" aria-hidden="true"></i>
+    </div>
+</div>
+
+<style>
+    .topside-pagination-panel {
+        width: 100%;
+        overflow: hidden;
+        white-space: nowrap;
+        text-align: center;
+        position: relative;
+        user-select: none;
+    }
+
+    .topside-pagination-panel.align-left {
+        text-align: left;
+    }
+
+    .topside-pagination-panel.align-right {
+        text-align: right;
+    }
+
+    .topside-page-gap,
+    .topside-page-no {
+        position: relative;
+        display: inline-block;
+        margin: 0 8px;
+        overflow: hidden;
+        width: 2em;
+        height: 2em;
+    }
+
+    .topside-page-gap span,
+    .topside-page-no span {
+        display: inline-block;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        text-align: center;
+        line-height: 2em;
+    }
+
+    .topside-page-no {
+        border-radius: 4px;
+        color: var(--topside-default-text-color, #374151);
+        border: 1px solid var(--topside-primary-border-color, #E2E8F0);
+        cursor: pointer;
+    }
+
+    .topside-page-no:hover {
+        border-color: var(--topside-default-text-hover-color, #298DFF80);
+    }
+
+    .topside-page-no:active {
+        top: 1px;
+        color: var(--topside-default-active-text-color, #0061FF);
+    }
+
+    .topside-page-no.selected {
+        color: var(--topside-default-active-text-color, #0061FF);
+        border-color: var(--topside-default-active-border-color, #0061FF80);
+        cursor: default;
+    }
+
+    .topside-page-no:focus-visible {
+        outline: 2px solid var(--topside-primary-border-color, #298DFF);
+        outline-offset: 1px;
+    }
+
+    .topside-page-no.selected:active {
+        top: 0;
+        color: var(--topside-pagination-selected-color, #ffffff);
+        background-color: var(--topside-button-primary-border-color, #42A5F5);
+    }
+
+    .topside-page-nav {
+        position: relative;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        margin: 0 4px;
+        width: 2em;
+        height: 2em;
+        border-radius: 4px;
+        color: var(--topside-default-text-color, #374151);
+        border: 1px solid var(--topside-primary-border-color, #E2E8F0);
+        cursor: pointer;
+        vertical-align: top;
+    }
+
+    .topside-page-nav:hover {
+        border-color: var(--topside-default-text-hover-color, #298DFF80);
+    }
+
+    .topside-page-nav:active {
+        top: 1px;
+        color: var(--topside-default-active-text-color, #0061FF);
+    }
+
+    .topside-page-nav:focus-visible {
+        outline: 2px solid var(--topside-primary-border-color, #298DFF);
+        outline-offset: 1px;
+    }
+
+    .topside-page-nav.disabled {
+        cursor: not-allowed;
+        opacity: 0.4;
+        pointer-events: none;
+    }
+
+    .topside-pagination-panel.plain .topside-page-nav {
+        background-color: inherit;
+        border: none;
+        color: #7f7f7f;
+    }
+
+    .topside-pagination-panel.plain .topside-page-nav:hover {
+        color: var(--topside-button-primary-border-color, #42A5F5);
+    }
+
+    .topside-pagination-panel.big .topside-page-nav {
+        width: 3em;
+        height: 3em;
+    }
+
+    /* Plain variant */
+    .topside-pagination-panel.plain .topside-page-no {
+        background-color: inherit;
+        border: none;
+    }
+
+    .topside-pagination-panel.plain .topside-page-no span {
+        color: #7f7f7f;
+    }
+
+    .topside-pagination-panel.plain .topside-page-no:hover span {
+        background-color: inherit;
+        color: var(--topside-button-primary-border-color, #42A5F5);
+    }
+
+    .topside-pagination-panel.plain .topside-page-no:active span {
+        color: var(--topside-button-primary-border-color, #42A5F5);
+    }
+
+    .topside-pagination-panel.plain .topside-page-no.selected span {
+        font-weight: 600;
+        color: var(--topside-pagination-selected-background-color, #333333);
+    }
+
+    /* Circle variant */
+    .topside-pagination-panel.circle .topside-page-no {
+        border-radius: 50%;
+    }
+
+    /* Big size */
+    .topside-pagination-panel.big .topside-page-gap,
+    .topside-pagination-panel.big .topside-page-no {
+        width: 3em;
+        height: 3em;
+    }
+
+    .topside-pagination-panel.big .topside-page-gap span,
+    .topside-pagination-panel.big .topside-page-no span {
+        line-height: 3em;
+    }
+</style>

package/dist/navigation/pagination/Pagination.svelte.d.ts

@@ -0,0 +1,15 @@
+import type { OnPageChange, Size } from "../../types";
+interface Props {
+    pageCount: number;
+    pageNo?: number;
+    /** 形状：plain / round / circle */
+    variant?: 'plain' | 'round' | 'circle';
+    style?: string;
+    /** 尺寸档位；'large' 对应旧的 big */
+    size?: Size;
+    theme?: string;
+    onchange?: OnPageChange;
+}
+declare const Pagination: import("svelte").Component<Props, {}, "pageNo">;
+type Pagination = ReturnType<typeof Pagination>;
+export default Pagination;

package/dist/navigation/pagination/README.md

@@ -0,0 +1,248 @@
+# Pagination Component
+
+A page-number pagination bar with smart ellipsis layout. Renders numbered buttons (1 … N-2 N-1 N, etc.) based on the current page, with three visual variants and a `big` size option. **No prev/next/first/last buttons** — just numbered pages.
+
+## Features
+
+- **Smart page range**: always shows first page, last page, and a window around the current page; uses `...` gaps to keep the bar compact for large page counts
+- **Three visual variants**: `plain` (text only), `round` (default, 4px-radius bordered squares), `circle` (perfectly round)
+- **`big` size mode**: 3em buttons instead of 2em
+- **Theme hook**: `data-theme="{theme}"` on the outer wrapper
+- **Skips redundant clicks**: clicking the already-selected page does nothing
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import Pagination from '@ticatec/topside-elements/Pagination';
+```
+
+## Basic Usage
+
+```svelte
+<script lang="ts">
+  import Pagination from '@ticatec/topside-elements/Pagination';
+
+  let currentPage = $state(1);
+  const totalPages = 10;
+
+  function onPageChange(page: number) {
+    currentPage = page;
+    console.log('Page changed to:', page);
+  }
+</script>
+
+<Pagination
+  pageNo={currentPage}
+  pageCount={totalPages}
+  onchange={onPageChange}
+/>
+```
+
+> **`pageNo` is NOT two-way bindable.** You must update your own state in the `onchange` handler — `bind:pageNo` is not supported. If you forget, the UI will never move off page 1.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `pageCount` | `number` | `0` | Total number of pages. With 0, nothing renders. |
+| `pageNo` | `number` | `1` | Current page. **Clamped internally** to `[1, pageCount]` for rendering — but the clamp does not propagate back to the parent. Keep your state in range yourself. |
+| `type` | `'plain' \| 'round' \| 'circle'` | `'round'` | Visual variant. `plain` = text-only no border, `round` = bordered with 4px radius, `circle` = bordered with 50% radius. |
+| `big` | `boolean` | `false` | 3em buttons (default 2em) |
+| `style` | `string` | `''` | Inline CSS on the outer wrapper |
+| `theme` | `string \| undefined` | `undefined` | Set as `data-theme` on the outer wrapper |
+| `onchange` | `((page: number) => void) \| undefined` | `undefined` | Fires when a page number is clicked. **Not fired when the clicked page equals the current `pageNo`.** |
+
+## Page Display Logic
+
+The bar always centers around the current page; gaps (`...`) replace runs of hidden middle pages. Branches by `pageCount` and `pageNo`:
+
+| `pageCount` | `pageNo` location | Rendered sequence |
+|-------------|-------------------|-------------------|
+| `< 6` | anywhere | `1 2 3 ... N` (all pages, no gaps) |
+| `≥ 6` | first or second | `1 2 3 … N` |
+| `≥ 6` | last or second-to-last | `1 … N-2 N-1 N` |
+| `≥ 6` | third | `1 2 3 4 … N` |
+| `≥ 6` | third-to-last | `1 … N-3 N-2 N-1 N` |
+| `≥ 6` | anywhere else | `1 … P-1 P P+1 … N` |
+
+So with `pageCount=20` and `pageNo=10`, the bar shows: `1 … 9 10 11 … 20`.
+
+## Examples
+
+### Data Table with Pagination
+
+```svelte
+<script lang="ts">
+  import Pagination from '@ticatec/topside-elements/Pagination';
+
+  let currentPage = $state(1);
+  const totalPages = 20;
+  const itemsPerPage = 10;
+
+  let data = $state<any[]>([]);
+
+  async function loadData(page: number) {
+    const startIndex = (page - 1) * itemsPerPage;
+    // Replace with your real fetch
+    data = Array.from({ length: itemsPerPage }, (_, i) => ({
+      id: startIndex + i + 1,
+      name: `Item ${startIndex + i + 1}`
+    }));
+  }
+
+  async function onPageChange(page: number) {
+    currentPage = page;
+    await loadData(page);
+  }
+
+  loadData(currentPage);
+</script>
+
+<table>
+  <thead><tr><th>ID</th><th>Name</th></tr></thead>
+  <tbody>
+    {#each data as item (item.id)}
+      <tr><td>{item.id}</td><td>{item.name}</td></tr>
+    {/each}
+  </tbody>
+</table>
+
+<Pagination
+  pageNo={currentPage}
+  pageCount={totalPages}
+  onchange={onPageChange}
+  style="margin-top: 20px;"
+/>
+```
+
+### Plain Variant (Text-Only)
+
+```svelte
+<Pagination
+  pageNo={currentPage}
+  pageCount={totalPages}
+  onchange={onPageChange}
+  type="plain"
+/>
+```
+
+Plain mode is good for compact UIs (e.g. inside a card header) — no borders, only the active page is bolded.
+
+### Circle Variant + Big Size
+
+```svelte
+<Pagination
+  pageNo={currentPage}
+  pageCount={totalPages}
+  onchange={onPageChange}
+  type="circle"
+  big
+/>
+```
+
+### With Custom Prev/Next Buttons
+
+The component renders only page numbers — wrap it to add prev/next:
+
+```svelte
+<script lang="ts">
+  import Pagination from '@ticatec/topside-elements/Pagination';
+  import Button from '@ticatec/topside-elements/Button';
+
+  let page = $state(1);
+  const total = 20;
+
+  function go(delta: number) {
+    const next = Math.min(Math.max(1, page + delta), total);
+    if (next !== page) page = next;
+  }
+</script>
+
+<div style="display: flex; align-items: center; gap: 8px; justify-content: center;">
+  <Button label="‹ Prev" disabled={page === 1}        onclick={() => go(-1)} />
+  <Pagination pageNo={page} pageCount={total} onchange={(p) => page = p} />
+  <Button label="Next ›" disabled={page === total}    onclick={() => go(1)} />
+</div>
+```
+
+## DOM Structure & CSS
+
+```html
+<div class="topside-pagination-panel {type}" class:big data-theme="..." style="...">
+  <!-- page number -->
+  <div class="topside-page-no" onclick={...} aria-hidden="true" class:selected>
+    <span tabindex="-1">{page}</span>
+  </div>
+
+  <!-- gap -->
+  <div class="topside-page-gap"><span>...</span></div>
+  ...
+</div>
+```
+
+### CSS Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `--topside-default-text-color` | Default page number text color |
+| `--topside-default-text-hover-color` | Hover border color |
+| `--topside-default-active-text-color` | Active page text color (active = pressed) |
+| `--topside-default-active-border-color` | Selected page border color |
+| `--topside-pagination-selected-color` | Selected page text color (when pressed — rare) |
+| `--topside-pagination-selected-background-color` | Plain variant selected text color |
+| `--topside-primary-border-color` | Default page border color |
+| `--topside-button-primary-border-color` | Plain hover/active text color + selected background |
+
+> The variable naming is inconsistent (`default-text-hover-color` is used for hover *border*, `pagination-selected-color` is used for `:active` of selected). Pin to the table above when overriding.
+
+### Variant-specific styles
+
+- **`plain`**: no border, transparent background. Selected page is bolded; hover/active change text color.
+- **`round`** (default): 1px border, `border-radius: 4px`. Hover changes border color; active gets blue text + 1px downward press.
+- **`circle`**: same as `round` but `border-radius: 50%`.
+- **`big`**: buttons become 3em × 3em (default 2em × 2em).
+
+### Alignment
+
+The wrapper has `text-align: center` by default. CSS classes `.align-left` and `.align-right` exist but **no prop exposes them** — set `style="text-align: left;"` on the wrapper directly if you need it.
+
+## Behavior Notes
+
+- **`pageNo` is clamped internally** for rendering (`[1, pageCount]`), but the clamp is local — your parent state isn't updated. If you pass `pageNo=50` with `pageCount=10`, the bar renders page 10 as selected, but your state still says 50. Keep your state in range.
+- **`onchange` is not fired for the current page.** Clicking the selected page is a no-op.
+- **No prev/next/first/last buttons.** Render your own around the component if you need them.
+- **`pageCount < 6` shows all pages** (no gaps). With `pageCount=5` you get `1 2 3 4 5`.
+- **Re-render on every prop change.** `buildPagination` runs in a `$effect`, so changing `pageNo`, `pageCount` rebuilds the array. Cheap; don't worry about it.
+- **The bar is `overflow: hidden`** — if the parent is narrow, buttons may clip. There's no scroll/wrap fallback.
+- **Every page button is `aria-hidden="true"`** with `tabindex="-1"` inside. See a11y below.
+
+## Accessibility (Significant Limitations)
+
+Same pattern as Navigator — this component is **not keyboard or screen-reader accessible**:
+
+1. **Every page button has `aria-hidden="true"`** — invisible to screen readers.
+2. **Inner `<span tabindex="-1">`** — explicitly removed from tab order.
+3. **`<div onclick>`** — not a real button. No Enter/Space, no `role="button"`.
+4. **Selected state conveyed by color alone** — no `aria-current="page"` or text alternative.
+5. **No focus styles.**
+
+For accessible pagination, fork the component or wrap each page number in a real `<button>` with `aria-label="Page N"` and `aria-current="page"` on the active one.
+
+## Best Practices
+
+1. **Update `pageNo` in your `onchange` handler** — there's no `bind:`.
+2. **Clamp your state to `[1, pageCount]`** — don't rely on the component's internal clamp leaking back.
+3. **Pair with prev/next buttons** if your users need them — the component is page-numbers-only.
+4. **Use `type="plain"` for compact UIs** (card headers, sidebars). `round` and `circle` work better in spacious footer bars.
+5. **Use `big` for touch UIs** — the default 2em buttons are small for fingers.
+6. **Don't rely on keyboard navigation** — see a11y note above.
+
+## Related Components
+
+- [PaginationPanel](../pagination_panel/README.md) — fuller-featured pagination (if it exists in your version)