@maestro-js/agent-skills 1.0.0-alpha.2 → 1.0.0-alpha.21

package/skills/maestro-examples/references/cadence/cadence-web/app/components/table/use-client-table.ts

@@ -0,0 +1,160 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add table --directory app
+
+import React from 'react'
+import { HeadlessTemplatedRowTable } from './headless-templated-row-table'
+import type { MatchSorterOptions } from 'match-sorter'
+
+type ClientFeatures<
+  TData extends HeadlessTemplatedRowTable.RowData,
+  FC extends HeadlessTemplatedRowTable.FilterConfig<TData> = {},
+  SC extends HeadlessTemplatedRowTable.SortConfig<TData> = {}
+> = [
+  ReturnType<typeof HeadlessTemplatedRowTable.rowCount<TData>>,
+  ReturnType<typeof HeadlessTemplatedRowTable.filtering<TData, HeadlessTemplatedRowTable.FilterConfig<TData, FC>>>,
+  ReturnType<typeof HeadlessTemplatedRowTable.search<TData>>,
+  ReturnType<typeof HeadlessTemplatedRowTable.sort<TData, SC>>,
+  ReturnType<typeof HeadlessTemplatedRowTable.rowSelection<TData>>,
+  ReturnType<typeof HeadlessTemplatedRowTable.pagination<TData>>
+]
+
+export function useClientTable<
+  TData extends HeadlessTemplatedRowTable.RowData,
+  FC extends HeadlessTemplatedRowTable.FilterConfig<NoInfer<TData>> = {},
+  SC extends HeadlessTemplatedRowTable.SortConfig<NoInfer<TData>> = {}
+>({
+  rows: rowsInput,
+  filters,
+  search,
+  sorts,
+  getRowId,
+  defaultPageSize,
+  onFiltersChange,
+  onSearchChange,
+  onSortChange,
+  onPaginationChange,
+  onRowSelectionChange,
+  manualFiltering,
+  manualSearch,
+  manualSort,
+  manualPagination
+}: {
+  rows: TData[]
+  filters?: FC & HeadlessTemplatedRowTable.FilterConfig<NoInfer<TData>, FC>
+  search?: MatchSorterOptions<TData>
+  sorts?: SC & HeadlessTemplatedRowTable.SortConfig<NoInfer<TData>, SC>
+  getRowId: (row: TData) => string
+  defaultPageSize?: number
+  manualFiltering?: boolean
+  onFiltersChange?: (
+    val:
+      | HeadlessTemplatedRowTable.FilterState<TData, FC>
+      | ((prev: HeadlessTemplatedRowTable.FilterState<TData, FC>) => HeadlessTemplatedRowTable.FilterState<TData, FC>)
+  ) => void
+  manualSearch?: boolean
+  onSearchChange?: (val: string | ((prev: string) => string)) => void
+  manualSort?: boolean
+  onSortChange?: (
+    val:
+      | HeadlessTemplatedRowTable.SortState<SC>
+      | ((prev: HeadlessTemplatedRowTable.SortState<SC>) => HeadlessTemplatedRowTable.SortState<SC>)
+  ) => void
+  manualPagination?: boolean
+  onPaginationChange?: (val: any) => void
+  onRowSelectionChange?: (val: Set<string>) => void
+}): HeadlessTemplatedRowTable.ReactTable<TData, ClientFeatures<TData, FC, SC>> {
+  const tableRef = React.useRef(null as HeadlessTemplatedRowTable.ReactTable<TData, ClientFeatures<TData, FC, SC>> | null)
+
+  const options = React.useMemo(() => {
+    const applyState = (key: string, val: any) => {
+      tableRef.current!.setState((prev: any) => ({
+        ...prev,
+        [key]: typeof val === 'function' ? val(prev[key]) : val
+      }))
+    }
+    const resetDependentState = (resetPagination: boolean) => {
+      tableRef.current!.setState((prev: any) => {
+        const resetPag = resetPagination && !manualPagination && prev.pagination?.skip !== 0
+        const resetSel = prev.rowSelection?.size > 0
+        if (!resetPag && !resetSel) return prev
+        return {
+          ...prev,
+          ...(resetPag ? { pagination: { ...prev.pagination, skip: 0 } } : {}),
+          ...(resetSel ? { rowSelection: new Set() } : {})
+        }
+      })
+    }
+
+    return {
+      onFiltersChange: (val: any) => {
+        if (onFiltersChange) onFiltersChange(val)
+        else applyState('filters', val)
+        resetDependentState(true)
+      },
+      onSearchChange: (val: any) => {
+        if (onSearchChange) onSearchChange(val)
+        else applyState('search', val)
+        resetDependentState(true)
+      },
+      onSortChange: (val: any) => {
+        if (onSortChange) onSortChange(val)
+        else applyState('sort', val)
+        resetDependentState(true)
+      },
+      onPaginationChange: (val: any) => {
+        if (onPaginationChange) onPaginationChange(val)
+        else applyState('pagination', val)
+        resetDependentState(false)
+      },
+      onRowSelectionChange,
+      manualFiltering,
+      manualSearch,
+      manualSort,
+      manualPagination
+    }
+  }, [
+    onFiltersChange,
+    onSearchChange,
+    onSortChange,
+    onPaginationChange,
+    onRowSelectionChange,
+    manualFiltering,
+    manualSearch,
+    manualSort,
+    manualPagination
+  ])
+
+  if (!tableRef.current) {
+    tableRef.current = HeadlessTemplatedRowTable.createTable({
+      features: [
+        HeadlessTemplatedRowTable.filtering<TData, HeadlessTemplatedRowTable.FilterConfig<TData, FC>>(
+          (filters ?? {}) as HeadlessTemplatedRowTable.FilterConfig<TData, FC>
+        ),
+        HeadlessTemplatedRowTable.search<TData>(search ?? {}),
+        HeadlessTemplatedRowTable.sort<TData, SC>((sorts ?? {}) as SC),
+        HeadlessTemplatedRowTable.rowCount(),
+        HeadlessTemplatedRowTable.rowSelection<TData>(getRowId),
+        HeadlessTemplatedRowTable.pagination<TData>(defaultPageSize ?? 10)
+      ],
+      rows: rowsInput,
+      ...options
+    }) as HeadlessTemplatedRowTable.ReactTable<TData, ClientFeatures<TData, FC, SC>>
+  }
+  const table = tableRef.current
+
+  const state = React.useSyncExternalStore(
+    table.subscribe,
+    () => table.state,
+    () => table.state
+  )
+  table.state = state
+
+  React.useEffect(() => {
+    table.setRows(rowsInput)
+  }, [rowsInput])
+  React.useEffect(() => {
+    table.setOptions(options)
+  }, [options])
+
+  return table
+}

package/skills/maestro-examples/references/cadence/cadence-web/app/components/table/use-client-table.type-test.ts

@@ -0,0 +1,220 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add table --directory app
+
+import { useClientTable } from './use-client-table'
+import type { TableLocalization } from './table-types'
+import type { Iso } from 'iso-fns'
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+type Expect<T extends true> = T
+type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false
+
+// =============================================================================
+// Setup
+// =============================================================================
+
+type Row = {
+  id: string
+  status: 'active' | 'inactive'
+  name: string
+  createdAt: string
+}
+
+// =============================================================================
+// Filter and sort config inference
+// =============================================================================
+
+function testFilterAndSortInference() {
+  const table = useClientTable({
+    rows: [] as Row[],
+    getRowId: (row) => row.id,
+    filters: {
+      status: (row, value) => row.status === value
+    },
+    sorts: {
+      newest: (a, b) => a.createdAt.localeCompare(b.createdAt),
+      oldest: (a, b) => b.createdAt.localeCompare(a.createdAt)
+    }
+  })
+
+  // getFilterConfig() keys match the provided filter names
+  type _FilterKeys = Expect<Equal<keyof ReturnType<typeof table.getFilterConfig>, 'status'>>
+
+  // getSortConfig() keys match the provided sort names
+  type _SortKeys = Expect<Equal<keyof ReturnType<typeof table.getSortConfig>, 'newest' | 'oldest'>>
+
+  // state.sort is the union of sort keys | null
+  type _SortState = Expect<Equal<typeof table.state.sort, 'newest' | 'oldest' | null>>
+
+  // state.filters keys match filter names
+  type _FilterStateKeys = Expect<Equal<keyof typeof table.state.filters, 'status'>>
+}
+
+// =============================================================================
+// Localization compatibility — select filter
+// =============================================================================
+
+function testLocalizationWithSelectFilter() {
+  const table = useClientTable({
+    rows: [] as Row[],
+    getRowId: (row) => row.id,
+    filters: {
+      status: (row, value) => row.status === value
+    },
+    sorts: {
+      newest: (a, b) => 0,
+      oldest: (a, b) => 0
+    }
+  })
+
+  type Loc = TableLocalization<
+    ReturnType<typeof table.getFilterConfig>,
+    ReturnType<typeof table.getSortConfig>
+  >
+
+  type _LocFilterKeys = Expect<Equal<keyof Loc['filters'], 'status'>>
+  type _LocSortKeys = Expect<Equal<keyof Loc['sorts'], 'newest' | 'oldest'>>
+
+  // Valid localization with typed option values
+  const _loc: Loc = {
+    filters: {
+      status: {
+        label: 'Status',
+        options: [
+          { label: 'Active', value: 'active' },
+          { label: 'Inactive', value: 'inactive' }
+        ]
+      }
+    },
+    sorts: {
+      newest: { label: 'Newest' },
+      oldest: { label: 'Oldest' }
+    }
+  }
+}
+
+// =============================================================================
+// Localization compatibility — date range filter
+// =============================================================================
+
+function testLocalizationWithDateRangeFilter() {
+  type RowWithDate = {
+    id: string
+    dateRange: { startDate: Iso.Date; endDate: Iso.Date }
+  }
+
+  const table = useClientTable({
+    rows: [] as RowWithDate[],
+    getRowId: (row) => row.id,
+    filters: {
+      dateRange: (row, value) => true
+    }
+  })
+
+  type Loc = TableLocalization<
+    ReturnType<typeof table.getFilterConfig>,
+    ReturnType<typeof table.getSortConfig>
+  >
+
+  // Valid: date-range filter accepts DateRangeTableFilter form
+  const _loc: Loc = {
+    filters: {
+      dateRange: { label: 'Date Range', type: 'date-range' }
+    },
+    sorts: {}
+  }
+
+  // Invalid: date-range filter rejects select-style options
+  const _badLoc: Loc = {
+    filters: {
+      dateRange: {
+        label: 'Date Range',
+        type: 'date-range',
+        // @ts-expect-error — select-style options array is not valid for date-range
+        options: [{ label: 'X', value: 'x' }]
+      }
+    },
+    sorts: {}
+  }
+}
+
+// =============================================================================
+// Filter predicate contextual typing — row and value are well typed
+// =============================================================================
+
+function testFilterPredicateContextualTyping() {
+  useClientTable({
+    rows: [] as Row[],
+    getRowId: (row) => row.id,
+    filters: {
+      // @ts-expect-error — 'nonExistent' doesn't exist on Row
+      status: (row, value) => row.nonExistent === value
+    }
+  })
+
+  useClientTable({
+    rows: [] as Row[],
+    getRowId: (row) => row.id,
+    filters: {
+      // value is Row['status'], comparing to a number should error
+      // @ts-expect-error — Row['status'] is not comparable to number
+      status: (row, value) => value === 123
+    }
+  })
+}
+
+// =============================================================================
+// Sort comparator contextual typing — row is well typed
+// =============================================================================
+
+function testSortComparatorContextualTyping() {
+  useClientTable({
+    rows: [] as Row[],
+    getRowId: (row) => row.id,
+    sorts: {
+      // @ts-expect-error — 'nonExistent' doesn't exist on Row
+      byName: (a, b) => a.nonExistent.localeCompare(b.name)
+    }
+  })
+}
+
+// =============================================================================
+// Negative: wrong localization option value
+// =============================================================================
+
+declare function checkLocalization(l: TableLocalization<{ status: 'active' | 'inactive' }, {}>): void
+
+function testWrongLocalizationOptionValue() {
+  checkLocalization({
+    filters: {
+      status: {
+        label: 'Status',
+        // @ts-expect-error — 'unknown' is not assignable to Row['status']
+        options: [{ label: 'Unknown', value: 'unknown' }]
+      }
+    },
+    sorts: {}
+  })
+}
+
+// =============================================================================
+// No filters/sorts → empty localization
+// =============================================================================
+
+function testNoFiltersOrSorts() {
+  const table = useClientTable({
+    rows: [] as Row[],
+    getRowId: (row) => row.id
+  })
+
+  type Loc = TableLocalization<
+    ReturnType<typeof table.getFilterConfig>,
+    ReturnType<typeof table.getSortConfig>
+  >
+
+  type _EmptyFilters = Expect<Equal<Loc['filters'], {}>>
+  type _EmptySorts = Expect<Equal<Loc['sorts'], {}>>
+}

package/skills/maestro-examples/references/cadence/cadence-web/app/components/table/use-server-table.ts

@@ -0,0 +1,195 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add table --directory app
+
+import React from 'react'
+import { useSearchParams as useSearchParamsRR } from 'react-router'
+import { HeadlessTemplatedRowTable } from './headless-templated-row-table'
+import { SearchParams } from '../../utils/use-query-state'
+import { type ServerTable } from './server-table'
+
+type ServerFilterConfig<TData extends HeadlessTemplatedRowTable.RowData, FC extends Record<string, any>> = {
+  [K in keyof FC & string]: HeadlessTemplatedRowTable.FilterPredicate<TData, K, NonNullable<FC[K]>>
+}
+
+type ServerSortConfig<TData extends HeadlessTemplatedRowTable.RowData, SortKeys extends string> = Record<
+  SortKeys,
+  HeadlessTemplatedRowTable.SortComparator<TData>
+>
+
+type ServerFeatures<
+  TData extends HeadlessTemplatedRowTable.RowData,
+  FC extends Record<string, any>,
+  SC extends Record<string, any>
+> = [
+  ReturnType<typeof HeadlessTemplatedRowTable.rowCount<TData>>,
+  ReturnType<typeof HeadlessTemplatedRowTable.filtering<TData, ServerFilterConfig<TData, FC>>>,
+  ReturnType<typeof HeadlessTemplatedRowTable.sort<TData, ServerSortConfig<TData, keyof SC & string>>>,
+  ReturnType<typeof HeadlessTemplatedRowTable.search<TData>>,
+  ReturnType<typeof HeadlessTemplatedRowTable.rowSelection<TData>>,
+  ReturnType<typeof HeadlessTemplatedRowTable.pagination<TData>>
+]
+
+const noopSearchCodec = SearchParams.codecs.string().default('')
+const noopPaginationLoader = SearchParams.createLoader({
+  limit: SearchParams.codecs.int().default(0),
+  skip: SearchParams.codecs.int().default(0)
+})
+
+export function useServerTable<
+  TData extends HeadlessTemplatedRowTable.RowData,
+  FC extends Record<string, any> = {},
+  SC extends Record<string, any> = {}
+>(
+  serverTable: ServerTable.ServerTable<TData, FC, SC>,
+  _options: {
+    getRowId: (row: TData) => string
+  }
+): HeadlessTemplatedRowTable.ReactTable<TData, ServerFeatures<TData, FC, SC>> {
+  type SortKey = keyof SC & string
+
+  const filterCodec = React.useMemo(
+    () => SearchParams.deserializeLoader(serverTable.filters),
+    [serverTable.filters]
+  ) as SearchParams.QueryStateLoader<FC>
+  const sortCodec = React.useMemo(() => SearchParams.deserializeCodec(serverTable.sorts), [serverTable.sorts])
+  const searchCodec = React.useMemo(
+    () => (serverTable.search ? SearchParams.deserializeCodec(serverTable.search) : noopSearchCodec),
+    [serverTable.search]
+  )
+  const paginationCodec = React.useMemo(
+    () => (serverTable.pagination ? SearchParams.deserializeLoader(serverTable.pagination) : noopPaginationLoader),
+    [serverTable.pagination]
+  )
+
+  const [filters] = SearchParams.useSearchParams(filterCodec)
+  const [sort] = SearchParams.useState('sort', sortCodec)
+  const sortValues = serverTable.sorts.values
+  const [search] = SearchParams.useState('search', searchCodec)
+  const [pagination, setPagination] = SearchParams.useSearchParams(paginationCodec)
+  const [, setURLParams] = useSearchParamsRR()
+
+  // Build noop configs for features (manual mode — predicates/comparators won't be called)
+  const filterConfig = React.useMemo(
+    () => Object.fromEntries(Object.keys(filterCodec ?? {}).map((key) => [key, () => true])),
+    [filterCodec]
+  ) as unknown as ServerFilterConfig<TData, FC>
+  const sortConfig = React.useMemo(
+    () => Object.fromEntries(sortValues.map((v) => [v, () => 0])),
+    [sortValues]
+  ) as unknown as ServerSortConfig<TData, SortKey>
+
+  const state = React.useMemo(
+    () => ({
+      filters,
+      sort: sort as SortKey | null,
+      search: search ?? '',
+      pagination: { limit: pagination.limit, skip: pagination.skip }
+    }),
+    [filters, sort, search, pagination]
+  )
+
+  const options = React.useMemo(
+    () => ({
+      manualFiltering: true as const,
+      manualSearch: true as const,
+      manualSort: true as const,
+      manualPagination: true as const,
+      onFiltersChange: (v: any) => {
+        setURLParams(
+          (prev) => {
+            const next = new URLSearchParams(prev)
+            const oldFilters = Object.fromEntries(
+              Object.entries(filterCodec).map(([name, codec]: [string, any]) => {
+                try {
+                  return [name, codec.decode(next.get(name)) ?? codec._def?.defaultValue ?? null]
+                } catch {
+                  return [name, codec._def?.defaultValue ?? null]
+                }
+              })
+            )
+            const newFilters = typeof v === 'function' ? v(oldFilters) : v
+            for (const [name, codec] of Object.entries(filterCodec) as [string, any][]) {
+              const encoded = codec.encode(newFilters[name])
+              if (
+                encoded === null ||
+                (codec._def?.defaultValue != null &&
+                  codec._def?.clearOnDefault &&
+                  encoded === codec.encode(codec._def?.defaultValue))
+              ) {
+                next.delete(name)
+              } else {
+                next.set(name, encoded)
+              }
+            }
+            next.delete('skip')
+            return next
+          },
+          { preventScrollReset: true, replace: true }
+        )
+        table.clearRowSelection?.()
+      },
+      onSortChange: (v: any) => {
+        setURLParams(
+          (prev) => {
+            const next = new URLSearchParams(prev)
+            const newSort = typeof v === 'function' ? v(sortCodec.decode(next.get('sort'))) : v
+            const encoded = sortCodec.encode(newSort)
+            if (encoded === null) next.delete('sort')
+            else next.set('sort', encoded)
+            next.delete('skip')
+            return next
+          },
+          { preventScrollReset: true, replace: true }
+        )
+        table.clearRowSelection?.()
+      },
+      onSearchChange: (v: any) => {
+        setURLParams(
+          (prev) => {
+            const next = new URLSearchParams(prev)
+            const newSearch = typeof v === 'function' ? v(next.get('search') ?? '') : v
+            if (newSearch) next.set('search', newSearch)
+            else next.delete('search')
+            next.delete('skip')
+            return next
+          },
+          { preventScrollReset: true, replace: true }
+        )
+        table.clearRowSelection?.()
+      },
+      onPaginationChange: (v: any) => setPagination(v, { preventScrollReset: true, replace: true }),
+      rowCount: serverTable.totalRows
+    }),
+    [filterCodec, sortCodec, setURLParams, setPagination, serverTable.totalRows]
+  )
+
+  const { current: table } = React.useRef(
+    HeadlessTemplatedRowTable.createTable({
+      features: [
+        HeadlessTemplatedRowTable.rowCount(),
+        HeadlessTemplatedRowTable.filtering<TData, ServerFilterConfig<TData, FC>>(filterConfig),
+        HeadlessTemplatedRowTable.sort<TData, ServerSortConfig<TData, SortKey>>(sortConfig),
+        HeadlessTemplatedRowTable.search<TData>({} as any),
+        HeadlessTemplatedRowTable.rowSelection<TData>(_options.getRowId),
+        HeadlessTemplatedRowTable.pagination<TData>(pagination.limit ?? 25)
+      ],
+      rows: serverTable.rows,
+      initialState: state,
+      ...options
+    })
+  )
+
+  table.state = React.useSyncExternalStore(
+    table.subscribe,
+    () => table.state,
+    () => table.state
+  )
+
+  table.setRows(serverTable.rows)
+
+  React.useEffect(() => {
+    table.setOptions({ state, ...options })
+  }, [state, options])
+
+  return table
+}