@manusiakemos/laravel-tanstack-react 0.1.0 → 0.1.1

package/src/components/DataTablePagination.tsx

@@ -0,0 +1,271 @@
+import type { Table } from '@tanstack/react-table'
+import {
+  ChevronLeft,
+  ChevronRight,
+  ChevronsLeft,
+  ChevronsRight,
+} from 'lucide-react'
+import type { ButtonHTMLAttributes, ReactNode, SelectHTMLAttributes } from 'react'
+
+import { cn } from '../lib/cn'
+import type { DataTableMeta } from '../types'
+import { Button } from './ui/button'
+import { Select } from './ui/select'
+
+export interface DataTablePaginationLabels {
+  previous?: ReactNode
+  next?: ReactNode
+  first?: ReactNode
+  last?: ReactNode
+  page?: string
+  of?: string
+  rowsPerPage?: string
+  /** Renderer for the row-count summary. */
+  summary?: (info: {
+    pageIndex: number
+    pageCount: number
+    pageSize: number
+    filtered: number
+    total: number | null
+  }) => ReactNode
+}
+
+export interface DataTablePaginationClassNames {
+  root?: string
+  info?: string
+  controls?: string
+  button?: string
+  select?: string
+  pageSize?: string
+}
+
+export interface DataTablePaginationRenderProps<TData> {
+  table: Table<TData>
+  meta: DataTableMeta | null
+  pageIndex: number
+  pageCount: number
+  pageSize: number
+  canPreviousPage: boolean
+  canNextPage: boolean
+  goToFirst: () => void
+  goToPrevious: () => void
+  goToNext: () => void
+  goToLast: () => void
+  setPageSize: (size: number) => void
+}
+
+export interface DataTablePaginationProps<TData> {
+  table: Table<TData>
+  /** Meta from `useDataTable`. Used for the row-count summary. */
+  meta?: DataTableMeta | null
+  /** Show the page-size selector. Defaults to false. */
+  showPageSize?: boolean
+  /** Available page size options when `showPageSize` is true. */
+  pageSizeOptions?: number[]
+  /** Show first/last page buttons. Defaults to false. */
+  showFirstLast?: boolean
+  /** Hide the "Page X of Y · N rows" summary. */
+  hideSummary?: boolean
+  /** Override individual labels / the summary renderer. */
+  labels?: DataTablePaginationLabels
+  /** Class for the root container. */
+  className?: string
+  /** Fine-grained class names for sub-elements. */
+  classNames?: DataTablePaginationClassNames
+  /** Extra props for the prev/next/first/last buttons. */
+  buttonProps?: Omit<
+    ButtonHTMLAttributes<HTMLButtonElement>,
+    'onClick' | 'disabled' | 'className' | 'type'
+  >
+  /** Extra props for the page-size <select>. */
+  selectProps?: Omit<
+    SelectHTMLAttributes<HTMLSelectElement>,
+    'value' | 'onChange' | 'className'
+  >
+  /**
+   * Full render override. Receives the pagination API so any custom UI can
+   * still drive the table.
+   */
+  render?: (props: DataTablePaginationRenderProps<TData>) => ReactNode
+}
+
+const DEFAULT_PAGE_SIZES = [10, 25, 50, 100]
+
+/**
+ * Shadcn-styled pagination controls (prev/next, optional first/last, optional
+ * page-size selector, row-count summary) wired to a TanStack `Table`.
+ */
+export function DataTablePagination<TData>(props: DataTablePaginationProps<TData>) {
+  const {
+    table,
+    meta = null,
+    showPageSize = false,
+    pageSizeOptions = DEFAULT_PAGE_SIZES,
+    showFirstLast = false,
+    hideSummary = false,
+    labels,
+    className,
+    classNames,
+    buttonProps,
+    selectProps,
+    render,
+  } = props
+
+  const state = table.getState().pagination
+  const pageIndex = state.pageIndex
+  const pageSize = state.pageSize
+  const pageCount = table.getPageCount()
+  const canPreviousPage = table.getCanPreviousPage()
+  const canNextPage = table.getCanNextPage()
+
+  const goToFirst = () => table.setPageIndex(0)
+  const goToPrevious = () => table.previousPage()
+  const goToNext = () => table.nextPage()
+  const goToLast = () => table.setPageIndex(Math.max(0, pageCount - 1))
+  const setPageSize = (size: number) => table.setPageSize(size)
+
+  if (render) {
+    return (
+      <>
+        {render({
+          table,
+          meta,
+          pageIndex,
+          pageCount,
+          pageSize,
+          canPreviousPage,
+          canNextPage,
+          goToFirst,
+          goToPrevious,
+          goToNext,
+          goToLast,
+          setPageSize,
+        })}
+      </>
+    )
+  }
+
+  const filtered = meta?.filtered ?? 0
+  const total = meta?.total ?? null
+
+  const summaryNode = labels?.summary
+    ? labels.summary({ pageIndex, pageCount, pageSize, filtered, total })
+    : (
+        <>
+          {labels?.page ?? 'Page'} {pageIndex + 1} {labels?.of ?? 'of'}{' '}
+          {Math.max(1, pageCount)}
+          {meta ? ` · ${filtered} rows` : null}
+        </>
+      )
+
+  return (
+    <div
+      className={cn(
+        'flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between',
+        className,
+        classNames?.root,
+      )}
+    >
+      {!hideSummary && (
+        <div
+          className={cn(
+            'text-sm text-muted-foreground',
+            classNames?.info,
+          )}
+        >
+          {summaryNode}
+        </div>
+      )}
+
+      <div
+        className={cn(
+          'flex items-center gap-2',
+          classNames?.controls,
+        )}
+      >
+        {showPageSize && (
+          <label
+            className={cn(
+              'flex items-center gap-2 text-sm text-muted-foreground',
+              classNames?.pageSize,
+            )}
+          >
+            <span>{labels?.rowsPerPage ?? 'Rows per page:'}</span>
+            <Select
+              value={pageSize}
+              onChange={(e) => setPageSize(Number(e.target.value))}
+              className={cn('h-9 w-[5rem]', classNames?.select)}
+              {...selectProps}
+            >
+              {pageSizeOptions.map((size) => (
+                <option key={size} value={size}>
+                  {size}
+                </option>
+              ))}
+            </Select>
+          </label>
+        )}
+
+        {showFirstLast && (
+          <Button
+            variant="outline"
+            size="icon"
+            onClick={goToFirst}
+            disabled={!canPreviousPage}
+            className={classNames?.button}
+            aria-label="Go to first page"
+            {...buttonProps}
+          >
+            {labels?.first ?? <ChevronsLeft className="h-4 w-4" />}
+          </Button>
+        )}
+
+        <Button
+          variant="outline"
+          onClick={goToPrevious}
+          disabled={!canPreviousPage}
+          className={classNames?.button}
+          aria-label="Go to previous page"
+          {...buttonProps}
+        >
+          {labels?.previous ?? (
+            <>
+              <ChevronLeft className="h-4 w-4" />
+              <span>Previous</span>
+            </>
+          )}
+        </Button>
+
+        <Button
+          variant="outline"
+          onClick={goToNext}
+          disabled={!canNextPage}
+          className={classNames?.button}
+          aria-label="Go to next page"
+          {...buttonProps}
+        >
+          {labels?.next ?? (
+            <>
+              <span>Next</span>
+              <ChevronRight className="h-4 w-4" />
+            </>
+          )}
+        </Button>
+
+        {showFirstLast && (
+          <Button
+            variant="outline"
+            size="icon"
+            onClick={goToLast}
+            disabled={!canNextPage}
+            className={classNames?.button}
+            aria-label="Go to last page"
+            {...buttonProps}
+          >
+            {labels?.last ?? <ChevronsRight className="h-4 w-4" />}
+          </Button>
+        )}
+      </div>
+    </div>
+  )
+}

package/src/components/DataTableSearch.tsx

@@ -0,0 +1,173 @@
+import { Search as SearchIcon } from 'lucide-react'
+import type { Table } from '@tanstack/react-table'
+import {
+  type FormEvent,
+  type InputHTMLAttributes,
+  type ReactNode,
+  useEffect,
+  useState,
+} from 'react'
+
+import { cn } from '../lib/cn'
+import { useDebouncedValue } from '../utils/useDebouncedValue'
+import { Button } from './ui/button'
+import { Input } from './ui/input'
+
+export interface DataTableSearchRenderProps {
+  /** Current uncommitted input value (pre-debounce / pre-submit). */
+  value: string
+  /** Update the input value (debounced commit if `debounce` is on). */
+  setValue: (next: string) => void
+  /** Immediately commit the current value to the table's global filter. */
+  submit: () => void
+  /** The value currently applied to the table's global filter. */
+  appliedValue: string
+}
+
+export type DataTableSearchDebounce = boolean | number
+
+export interface DataTableSearchProps<TData> {
+  table: Table<TData>
+  /**
+   * Debounce behavior:
+   *   - `true`  → debounced with default delay (300ms)
+   *   - number  → debounced with the given delay in ms
+   *   - `false` → no debounce; instead the component renders a Search button
+   *               and only commits to the table on submit (button click / Enter)
+   *
+   * Defaults to `true`.
+   */
+  debounce?: DataTableSearchDebounce
+  /** Placeholder text for the default input. */
+  placeholder?: string
+  /** Label for the search submit button (when `debounce` is `false`). */
+  submitLabel?: ReactNode
+  /** Class for the root wrapper element (ignored when `render` is provided). */
+  className?: string
+  /** Class merged into the underlying shadcn Input. */
+  inputClassName?: string
+  /** Class merged into the submit Button (when `debounce` is `false`). */
+  buttonClassName?: string
+  /** Extra props spread onto the underlying Input. */
+  inputProps?: Omit<
+    InputHTMLAttributes<HTMLInputElement>,
+    'value' | 'onChange' | 'type' | 'className'
+  >
+  /** Fired whenever the search value is committed to the table. */
+  onSearch?: (value: string) => void
+  /**
+   * Full render override. Receives the controlled value, setter, and a manual
+   * `submit()` so you can drop in any custom UI.
+   */
+  render?: (props: DataTableSearchRenderProps) => ReactNode
+}
+
+const DEFAULT_DEBOUNCE_MS = 300
+
+/**
+ * Debounced (or manual-submit) global search wired to a TanStack `Table`.
+ *
+ * @example Debounced (default)
+ * <DataTableSearch table={table} placeholder="Search users..." />
+ *
+ * @example Manual submit (search button)
+ * <DataTableSearch table={table} debounce={false} placeholder="Search..." />
+ *
+ * @example Custom UI
+ * <DataTableSearch
+ *   table={table}
+ *   render={({ value, setValue, submit }) => (
+ *     <MyCombobox value={value} onChange={setValue} onSubmit={submit} />
+ *   )}
+ * />
+ */
+export function DataTableSearch<TData>(props: DataTableSearchProps<TData>) {
+  const {
+    table,
+    debounce = true,
+    placeholder = 'Search...',
+    submitLabel,
+    className,
+    inputClassName,
+    buttonClassName,
+    inputProps,
+    onSearch,
+    render,
+  } = props
+
+  const isDebounced = debounce !== false
+  const debounceMs =
+    typeof debounce === 'number' ? debounce : DEFAULT_DEBOUNCE_MS
+
+  const appliedValue = (table.getState().globalFilter as string | undefined) ?? ''
+  const [value, setValue] = useState(appliedValue)
+  const debounced = useDebouncedValue(value, debounceMs)
+
+  const commit = (next: string) => {
+    if (next === appliedValue) return
+    table.setGlobalFilter(next)
+    onSearch?.(next)
+  }
+
+  // Debounced auto-commit. Disabled entirely when `debounce={false}`.
+  useEffect(() => {
+    if (!isDebounced) return
+    commit(debounced)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [debounced, isDebounced, table])
+
+  // Keep local state in sync if the table's filter is changed elsewhere.
+  useEffect(() => {
+    setValue(appliedValue)
+  }, [appliedValue])
+
+  const submit = () => commit(value)
+
+  if (render) {
+    return <>{render({ value, setValue, submit, appliedValue })}</>
+  }
+
+  const handleFormSubmit = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault()
+    submit()
+  }
+
+  // Debounced mode → just an input, no form / button needed.
+  if (isDebounced) {
+    return (
+      <Input
+        type="search"
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        placeholder={placeholder}
+        className={cn(className, inputClassName)}
+        {...inputProps}
+      />
+    )
+  }
+
+  // Manual mode → input + submit button, wrapped in a form so Enter submits.
+  return (
+    <form
+      onSubmit={handleFormSubmit}
+      className={cn('flex w-full max-w-md items-center gap-2', className)}
+    >
+      <Input
+        type="search"
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        placeholder={placeholder}
+        className={inputClassName}
+        {...inputProps}
+      />
+      <Button type="submit" className={buttonClassName}>
+        {submitLabel ?? (
+          <>
+            <SearchIcon className="h-4 w-4" aria-hidden="true" />
+            <span>Search</span>
+          </>
+        )}
+      </Button>
+    </form>
+  )
+}

package/src/components/layouts/DataTableSplitLayout.tsx

@@ -0,0 +1,153 @@
+import type { Table as TanStackTable } from '@tanstack/react-table'
+import type { ReactNode } from 'react'
+
+import { cn } from '../../lib/cn'
+import type { DataTableMeta } from '../../types'
+import { DataTable, type DataTableProps } from '../DataTable'
+import {
+  DataTablePagination,
+  type DataTablePaginationProps,
+} from '../DataTablePagination'
+import {
+  DataTableSearch,
+  type DataTableSearchProps,
+} from '../DataTableSearch'
+
+export interface DataTableSplitLayoutClassNames {
+  root?: string
+  toolbar?: string
+  toolbarLeft?: string
+  toolbarRight?: string
+  body?: string
+  footer?: string
+}
+
+export interface DataTableSplitLayoutProps<TData> {
+  table: TanStackTable<TData>
+  meta?: DataTableMeta | null
+  loading?: boolean
+
+  /**
+   * Right-side toolbar slot — typically one or more `<DataTableFilter />`s.
+   * Rendered to the right of the search input on the same row.
+   */
+  filters?: ReactNode
+  /**
+   * Optional far-right toolbar slot for page-level actions (e.g. an
+   * "+ Add" button). Appears after `filters`.
+   */
+  actions?: ReactNode
+
+  /**
+   * Override the entire search slot. By default, a `<DataTableSearch />`
+   * wired to `table` is rendered with sensible defaults.
+   */
+  search?: ReactNode
+
+  /** Forwarded to the auto-rendered `<DataTableSearch />`. */
+  searchProps?: Omit<DataTableSearchProps<TData>, 'table'>
+  /** Forwarded to the auto-rendered `<DataTable />`. */
+  tableProps?: Omit<DataTableProps<TData>, 'table' | 'loading'>
+  /** Forwarded to the auto-rendered `<DataTablePagination />`. */
+  paginationProps?: Omit<DataTablePaginationProps<TData>, 'table' | 'meta'>
+
+  className?: string
+  classNames?: DataTableSplitLayoutClassNames
+}
+
+/**
+ * Pre-built "split toolbar" layout: search on the left, filters/actions on
+ * the right; pagination info on the left, controls on the right.
+ *
+ * @example
+ * <DataTableSplitLayout
+ *   table={table}
+ *   meta={meta}
+ *   loading={loading}
+ *   searchProps={{ placeholder: 'Search users...' }}
+ *   filters={
+ *     <>
+ *       <DataTableFilter table={table} columnId="status" options={statusOpts} />
+ *       <DataTableFilter table={table} columnId="role" type="multiselect" options={roleOpts} />
+ *     </>
+ *   }
+ *   actions={<Button>+ Add user</Button>}
+ *   paginationProps={{ showPageSize: true, showFirstLast: true }}
+ * />
+ */
+export function DataTableSplitLayout<TData>(
+  props: DataTableSplitLayoutProps<TData>,
+) {
+  const {
+    table,
+    meta = null,
+    loading = false,
+    filters,
+    actions,
+    search,
+    searchProps,
+    tableProps,
+    paginationProps,
+    className,
+    classNames,
+  } = props
+
+  const searchNode = search ?? (
+    <DataTableSearch
+      table={table}
+      placeholder="Search..."
+      className="w-full max-w-md"
+      {...searchProps}
+    />
+  )
+
+  return (
+    <div
+      className={cn(
+        'flex flex-col gap-4',
+        className,
+        classNames?.root,
+      )}
+    >
+      <div
+        className={cn(
+          'flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between',
+          classNames?.toolbar,
+        )}
+      >
+        <div
+          className={cn(
+            'flex-1 min-w-0',
+            classNames?.toolbarLeft,
+          )}
+        >
+          {searchNode}
+        </div>
+
+        {(filters || actions) && (
+          <div
+            className={cn(
+              'flex flex-wrap items-center gap-2',
+              classNames?.toolbarRight,
+            )}
+          >
+            {filters}
+            {actions}
+          </div>
+        )}
+      </div>
+
+      <div className={classNames?.body}>
+        <DataTable table={table} loading={loading} {...tableProps} />
+      </div>
+
+      <div className={classNames?.footer}>
+        <DataTablePagination
+          table={table}
+          meta={meta}
+          {...paginationProps}
+        />
+      </div>
+    </div>
+  )
+}

package/src/components/ui/button.tsx

@@ -0,0 +1,49 @@
+import { cva, type VariantProps } from 'class-variance-authority'
+import { type ButtonHTMLAttributes, forwardRef } from 'react'
+
+import { cn } from '../../lib/cn'
+
+export const buttonVariants = cva(
+  'inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
+        destructive:
+          'bg-destructive text-destructive-foreground hover:bg-destructive/90',
+        outline:
+          'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
+        secondary:
+          'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+        ghost: 'hover:bg-accent hover:text-accent-foreground',
+        link: 'text-primary underline-offset-4 hover:underline',
+      },
+      size: {
+        default: 'h-10 px-4 py-2',
+        sm: 'h-9 rounded-md px-3',
+        lg: 'h-11 rounded-md px-8',
+        icon: 'h-10 w-10',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'default',
+    },
+  },
+)
+
+export interface ButtonProps
+  extends ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {}
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, size, type = 'button', ...props }, ref) => (
+    <button
+      ref={ref}
+      type={type}
+      className={cn(buttonVariants({ variant, size }), className)}
+      {...props}
+    />
+  ),
+)
+Button.displayName = 'Button'

package/src/components/ui/input.tsx

@@ -0,0 +1,20 @@
+import { forwardRef, type InputHTMLAttributes } from 'react'
+
+import { cn } from '../../lib/cn'
+
+export type InputProps = InputHTMLAttributes<HTMLInputElement>
+
+export const Input = forwardRef<HTMLInputElement, InputProps>(
+  ({ className, type = 'text', ...props }, ref) => (
+    <input
+      ref={ref}
+      type={type}
+      className={cn(
+        'flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50',
+        className,
+      )}
+      {...props}
+    />
+  ),
+)
+Input.displayName = 'Input'

package/src/components/ui/select.tsx

@@ -0,0 +1,27 @@
+import { forwardRef, type SelectHTMLAttributes } from 'react'
+
+import { cn } from '../../lib/cn'
+
+export type SelectProps = SelectHTMLAttributes<HTMLSelectElement>
+
+/**
+ * Shadcn-styled native <select>. We use the native element (not Radix) to
+ * keep the dependency footprint minimal; consumers who want a Radix-based
+ * popover select can swap it in via the `render` prop on the parent
+ * component.
+ */
+export const Select = forwardRef<HTMLSelectElement, SelectProps>(
+  ({ className, multiple, ...props }, ref) => (
+    <select
+      ref={ref}
+      multiple={multiple}
+      className={cn(
+        'flex w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50',
+        multiple ? 'min-h-[6rem]' : 'h-10',
+        className,
+      )}
+      {...props}
+    />
+  ),
+)
+Select.displayName = 'Select'