@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/server-table.ts

@@ -0,0 +1,146 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add table --directory app
+
+import { matchSorter, type MatchSorterOptions } from 'match-sorter'
+import { SearchParams } from '../../utils/use-query-state'
+import type { SearchParams as SearchParamsTypes } from '../../utils/use-query-state'
+import type { HeadlessTemplatedRowTable } from './headless-templated-row-table'
+
+export declare namespace ServerTable {
+  type RowData = HeadlessTemplatedRowTable.RowData
+
+  type ServerTableOptions<TData extends RowData, FC extends Record<string, any>, SC extends Record<string, any>> = {
+    rows: TData[]
+    url: string | URL
+    filters?: FilterFieldMap<TData, FC>
+    sorts?: HeadlessTemplatedRowTable.SortConfig<TData, SC>
+    defaultSort?: HeadlessTemplatedRowTable.SortState<SC>
+    search?: MatchSorterOptions<TData>
+    pagination?: number
+  }
+
+  type ServerTable<TData extends RowData, FC extends Record<string, any>, SC extends Record<string, any>> = {
+    rows: TData[]
+    totalRows: number
+    filters: SerializedFilterCodecs<FilterFieldMap<TData, FC>>
+    sorts: SerializedSortCodec<SC>
+    search: SearchParamsTypes.CodecDef<string | null> | null
+    pagination: {
+      limit: SearchParamsTypes.CodecDef<number | null>
+      skip: SearchParamsTypes.CodecDef<number | null>
+    } | null
+  }
+
+  // ---- Filtering ----
+
+  type FilterField<TData extends RowData, Name extends string = string, Value = any> = {
+    filter: HeadlessTemplatedRowTable.FilterPredicate<TData, Name, NonNullable<Value>>
+    codec: SearchParamsTypes.Codec<SearchParamsTypes.CodecDef<Value>>
+  }
+
+  type FilterFieldMap<TData extends RowData, FC extends Record<string, any> = Record<string, any>> = {
+    [K in keyof FC & string]: FilterField<TData, K, FC[K]>
+  }
+
+  type ExtractFilterValue<C extends FilterField<any, any, any>> = Parameters<C['filter']>[1]
+
+  type FilterValues<TData extends RowData, Def extends FilterFieldMap<TData>> = {
+    [key in keyof Def]: ExtractFilterValue<Def[key]> | null | undefined
+  }
+
+  type SerializedFilterCodecs<Def extends FilterFieldMap<any>> = {
+    [K in keyof Def & string]: SearchParamsTypes.SerializedCodec<Def[K]['codec']>
+  }
+
+  // ---- Sorting ----
+
+  type SortCodec<SC extends Record<string, any>> = SearchParamsTypes.Codec<
+    SearchParamsTypes.CodecDef<(keyof SC & string) | null>
+  >
+
+  type SerializedSortCodec<SC extends Record<string, any>> = SearchParamsTypes.SerializedCodec<SortCodec<SC>> & {
+    values: readonly (keyof SC & string)[]
+  }
+}
+
+export function createServerTable<
+  TData extends ServerTable.RowData,
+  FC extends Record<string, any> = {},
+  SC extends Record<string, any> = {}
+>(config: ServerTable.ServerTableOptions<TData, FC, SC>): ServerTable.ServerTable<TData, FC, SC> {
+  type Def = ServerTable.FilterFieldMap<TData, FC>
+  let rows = config.rows
+
+  // Build a unified loader from all feature codecs and read state from URL
+  const filterDef = config.filters
+  const filterKeys = filterDef ? (Object.keys(filterDef) as (keyof FC & string)[]) : []
+  const sortKeys = config.sorts ? (Object.keys(config.sorts) as (keyof SC & string)[]) : []
+
+  // Build codecs once
+  const sortCodec = config.sorts
+    ? SearchParams.codecs.enum(sortKeys).default(config.defaultSort ?? null)
+    : SearchParams.codecs.enum([] as string[])
+  const searchCodec = config.search ? SearchParams.codecs.string().default('') : null
+  const limitCodec = config.pagination != null ? SearchParams.codecs.int().default(config.pagination) : null
+  const skipCodec = config.pagination != null ? SearchParams.codecs.int().default(0) : null
+
+  const loader = {
+    ...Object.fromEntries(filterKeys.map((key) => [key, filterDef![key]!.codec])),
+    ...(config.sorts ? { sort: sortCodec } : {}),
+    ...(searchCodec ? { search: searchCodec } : {}),
+    ...(limitCodec && skipCodec ? { limit: limitCodec, skip: skipCodec } : {})
+  }
+
+  const params = SearchParams.getSearchParamsState(config.url, loader)
+
+  // Filtering
+  const filterCodecs = filterDef
+    ? (Object.fromEntries(
+        filterKeys.map((key) => [key, SearchParams.serializeCodec(filterDef[key]!.codec)])
+      ) as ServerTable.SerializedFilterCodecs<Def>)
+    : ({} as ServerTable.SerializedFilterCodecs<Def>)
+
+  rows = rows.filter((row) =>
+    filterKeys.every((f) => {
+      const value = (params as Record<string, any>)[f]
+      if (value == null) return true
+      return filterDef![f]!.filter(row, value, f)
+    })
+  )
+
+  // Search
+  if (config.search && searchCodec) {
+    const query = (params as any).search as string
+    if (query) {
+      rows = query.split(' ').reduce((results, term) => matchSorter(results, term, config.search!), rows)
+    }
+  }
+
+  // Sort
+  if (config.sorts) {
+    const sortKey = ((params as any).sort as string) || null
+    if (sortKey && config.sorts[sortKey as keyof SC & string]) {
+      rows = [...rows].sort((a, b) => config.sorts![sortKey as keyof SC & string]!(a, b, sortKey))
+    }
+  }
+
+  // Pagination
+  const totalRows = rows.length
+  if (config.pagination != null) {
+    const limit = ((params as any).limit as number) ?? config.pagination
+    const skip = ((params as any).skip as number) ?? 0
+    rows = rows.slice(skip, skip + limit)
+  }
+
+  return {
+    rows,
+    totalRows,
+    filters: filterCodecs,
+    sorts: SearchParams.serializeCodec(sortCodec) as ServerTable.SerializedSortCodec<SC>,
+    search: searchCodec ? SearchParams.serializeCodec(searchCodec) : null,
+    pagination:
+      limitCodec && skipCodec
+        ? { limit: SearchParams.serializeCodec(limitCodec), skip: SearchParams.serializeCodec(skipCodec) }
+        : null
+  }
+}

package/skills/maestro-examples/references/cadence/cadence-web/app/components/table/table-actions.tsx

@@ -0,0 +1,79 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add table --directory app
+
+import React from 'react'
+import { twMerge } from 'tailwind-merge'
+import { Button, type ButtonProps } from '../button'
+import { Menu, type MenuProps, type MenuItemProps, type MenuLinkItemProps } from '../menu'
+import { Icon } from '../icon'
+
+// ── TableActionButton ────────────────────────────────────────────────────────
+// Primary action button for the table toolbar (e.g. "Add person").
+// Defaults to contained/primary/sm — pass variant/color/size to override.
+
+export type TableActionButtonProps = ButtonProps
+
+export function TableActionButton({ size = 'md', children, ...props }: TableActionButtonProps) {
+  return (
+    <Button size={size} {...props}>
+      {children}
+    </Button>
+  )
+}
+
+// ── TableMenu ────────────────────────────────────────────────────────────────
+// Secondary actions dropdown for the table toolbar (e.g. "More").
+// Renders a neutral outlined trigger with a chevron, and a standard Menu popover.
+
+export type TableMenuProps = {
+  label?: string
+  children?: React.ReactNode
+  placement?: MenuProps['placement']
+}
+
+function TableMenuMain({ label = 'More', children, placement }: TableMenuProps) {
+  return (
+    <Menu
+      Button={
+        <Button variant="outlined" color="neutral" size="md">
+          {label}
+          <Icon name="chevron-down" className="size-4 text-neutral-400" />
+        </Button>
+      }
+      placement={placement}
+    >
+      {children}
+    </Menu>
+  )
+}
+
+export const TableMenu = Object.assign(TableMenuMain, {
+  Item: Menu.Item,
+  LinkItem: Menu.LinkItem,
+  Group: Menu.Group,
+  Separator: Menu.Separator
+})
+
+// ── TableSelectionAction ────────────────────────────────────────────────────
+// Compact action button for the multi-select selection bar context.
+
+export function TableSelectionActions({ children }: { children: React.ReactNode }) {
+  return <div className="flex items-center gap-1">{children}</div>
+}
+
+export type TableSelectionActionProps = React.ComponentProps<'button'>
+
+export function TableSelectionAction({ children, className, ...props }: TableSelectionActionProps) {
+  return (
+    <button
+      type="button"
+      {...props}
+      className={twMerge(
+        'inline-flex items-center rounded px-2 py-0.5 text-sm font-medium text-primary-700 hover:text-primary-900 hover:bg-primary-100 disabled:opacity-50 disabled:cursor-not-allowed',
+        className
+      )}
+    >
+      {children}
+    </button>
+  )
+}

package/skills/maestro-examples/references/cadence/cadence-web/app/components/table/table-container.tsx

@@ -0,0 +1,176 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add table --directory app
+
+import {
+  TableBody,
+  TableCell,
+  TableDescription,
+  TableFooter,
+  TableMain,
+  TableRow,
+  TableRowContextProvider,
+  TableTitle,
+  TableTitleLink
+} from './table-primitives'
+import type { StandardTable } from './table-types'
+import { TableHeader, type TableHeaderProps, TableSearch } from './table-toolbar'
+import { TableDateRangeFilter } from './table-filters/date-range-filter'
+import { TableSelectSort } from './table-filters/sort'
+import { TableSelectFilter } from './table-filters/select-filter'
+import type { TableFilterLocalization, TableLocalization } from './table-types'
+import { twMerge } from 'tailwind-merge'
+import React from 'react'
+import type { Iso } from 'iso-fns'
+
+export function TableContainer<TTable extends StandardTable>({
+  table,
+  localization,
+  children,
+  actions,
+  noRowElement = <StandardNoRows />,
+  multiSelect,
+  multiSelectActions,
+  hideActionsOnMobile = true,
+  stickyHeader = true,
+  hideSort,
+  hideSearch,
+  tableBodyClassName,
+  headerAction,
+  hideResultCount,
+  totalRows: totalRowsProp,
+  ...props
+}: React.ComponentProps<'div'> & {
+  table: TTable
+  localization: TableLocalization<ReturnType<TTable['getFilterConfig']>, ReturnType<TTable['getSortConfig']>>
+  actions?: React.ReactNode
+  noRowElement?: React.ReactNode
+  multiSelect?: boolean
+  hideActionsOnMobile?: boolean
+  hideSort?: boolean
+  hideSearch?: boolean
+  stickyHeader?: boolean
+  multiSelectActions?: React.ReactNode
+  tableBodyClassName?: string
+  headerAction?: TableHeaderProps['action']
+  hideResultCount?: boolean
+  totalRows?: number
+}) {
+  const rows = table.getRows()
+  const filterConfig = table.getFilterConfig()
+  const sortConfig = table.getSortConfig()
+  const filterKeys = Object.keys(filterConfig).filter((k) => k in localization.filters)
+  const sortKeys = Object.keys(sortConfig).filter((k) => k !== 'mostRelevant' && k in localization.sorts)
+
+  const hasFilters = React.useMemo(() => {
+    const filters = table.state.filters ?? {}
+    const hasActiveFilters = Object.entries(filters).some(([, value]) => value != null)
+    const hasSort = table.state.sort != null
+    const hasSearch = (table.state.search ?? '') !== ''
+    return hasActiveFilters || hasSort || hasSearch
+  }, [table.state.filters, table.state.sort, table.state.search])
+
+  return (
+    <div {...props}>
+      {/* Search + actions outside the card */}
+      <TableSearch
+        table={table}
+        placeholder={localization.searchPlaceholder}
+        actions={actions}
+        hasFilters={hasFilters}
+        hideSearch={hideSearch}
+        hideActionsOnMobile={hideActionsOnMobile}
+      />
+
+      {/* Bordered card container */}
+      <div className="rounded-lg border border-gray-950/10 overflow-hidden">
+        <TableMain className={twMerge(stickyHeader && 'relative')}>
+          <TableHeader
+            table={table}
+            multiSelect={multiSelect}
+            multiSelectActions={multiSelectActions}
+            sticky={stickyHeader}
+            hide={!!(hideSort && filterKeys.length === 0 && !multiSelect)}
+            action={headerAction}
+          >
+            <div className={twMerge('flex flex-nowrap items-center gap-x-1', hideSort && 'mr-1')}>
+              {filterKeys.map((f) => {
+                const filter = localization.filters[f] as TableFilterLocalization
+                if (filter.type === 'date-range') {
+                  return (
+                    <TableDateRangeFilter
+                      table={table}
+                      key={f}
+                      name={f}
+                      label={filter.label}
+                      options={filter.options}
+                      value={table.state.filters[f] as { startDate: Iso.Date; endDate: Iso.Date }}
+                    />
+                  )
+                } else {
+                  return (
+                    <TableSelectFilter
+                      table={table}
+                      label={filter.label}
+                      name={f}
+                      options={filter.options}
+                      autoComplete={filter.autoComplete}
+                      value={table.state.filters[f]}
+                      key={f}
+                    />
+                  )
+                }
+              })}
+            </div>
+            <div className={twMerge('flex flex-nowrap items-center ml-1 mr-1', hideSort && 'hidden')}>
+              <TableSelectSort
+                table={table}
+                value={table.state.sort}
+                options={sortKeys.map((s) => ({ value: s, label: localization.sorts[s]?.label ?? s }))}
+                search={table.state.search}
+              />
+            </div>
+          </TableHeader>
+          <TableRowContextProvider value={{ table, multiSelect }}>
+            {rows.length ? <TableBody className={tableBodyClassName}>{children}</TableBody> : noRowElement}
+          </TableRowContextProvider>
+          {rows.length ? <TableFooter table={table} hideResultCount={hideResultCount} /> : null}
+        </TableMain>
+      </div>
+    </div>
+  )
+}
+
+export function BasicTable({
+  table,
+  noRowElement = <StandardNoRows />,
+  children,
+  shouldHideFooter,
+  ...props
+}: React.ComponentProps<'div'> & {
+  table: StandardTable
+  noRowElement?: React.ReactNode
+  shouldHideFooter?: boolean
+}) {
+  const rows = table.getRows()
+  return (
+    <div {...props}>
+      <div className="rounded-lg border border-gray-950/10 overflow-hidden">
+        <TableMain>
+          <TableRowContextProvider value={{ table }}>
+            {rows.length ? <TableBody>{children}</TableBody> : noRowElement}
+          </TableRowContextProvider>
+          {rows.length > 0 && !shouldHideFooter ? <TableFooter table={table} /> : null}
+        </TableMain>
+      </div>
+    </div>
+  )
+}
+
+function StandardNoRows() {
+  return (
+    <div className="text-center py-8">
+      <h3 className="mt-2 text-sm font-semibold text-gray-900">No results</h3>
+      <p className="mt-1 text-sm text-gray-500">No results were found matching your query.</p>
+    </div>
+  )
+}

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

@@ -0,0 +1,158 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add table --directory app
+
+import type { StandardTable, TableLocalization, TableFilterLocalization } 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 — concrete filter/sort configs
+// =============================================================================
+
+type StatusValue = 'active' | 'inactive'
+type DateRangeValue = { startDate: Iso.Date; endDate: Iso.Date }
+
+type FC = { status: StatusValue; dateRange: DateRangeValue }
+type SC = { newest: null; oldest: null }
+
+type MyTable = StandardTable<FC, SC>
+type MyLocalization = TableLocalization<FC, SC>
+
+// =============================================================================
+// TableFilterLocalization discriminates on value type
+// =============================================================================
+
+// String union → DefaultTableFilter (has options array with typed values, no `type` discriminant)
+const _selectFilter: TableFilterLocalization<StatusValue> = {
+  label: 'Status',
+  options: [{ label: 'Active', value: 'active' }, { label: 'Inactive', value: 'inactive' }]
+}
+
+// Date range → DateRangeTableFilter (type: 'date-range', no value-typed options)
+const _dateFilter: TableFilterLocalization<DateRangeValue> = {
+  label: 'Date range',
+  type: 'date-range'
+}
+
+// date-range value rejects DefaultTableFilter form
+const _dateFilterRejectsSelect: TableFilterLocalization<DateRangeValue> = {
+  label: 'Date range',
+  type: 'date-range',
+  // @ts-expect-error — DefaultTableFilter 'options' shape is not valid for date-range
+  options: [{ label: 'Last 7 days', value: 'last7' }]
+}
+
+// string-union value rejects DateRangeTableFilter form
+const _selectFilterRejectsDateRange: TableFilterLocalization<StatusValue> = {
+  label: 'Status',
+  // @ts-expect-error — type: 'date-range' is not valid for a select filter
+  type: 'date-range'
+}
+
+// =============================================================================
+// TableLocalization requires the exact filter + sort keys
+// =============================================================================
+
+type _FiltersHasKeys = Expect<Equal<keyof MyLocalization['filters'], 'status' | 'dateRange'>>
+type _SortsHasKeys = Expect<Equal<keyof MyLocalization['sorts'], 'newest' | 'oldest'>>
+type _SortShape = Expect<Equal<MyLocalization['sorts']['newest'], { label: string }>>
+
+// =============================================================================
+// Full valid localization object
+// =============================================================================
+
+const _valid: MyLocalization = {
+  filters: {
+    status: {
+      label: 'Status',
+      options: [
+        { label: 'Active', value: 'active' },
+        { label: 'Inactive', value: 'inactive' }
+      ]
+    },
+    dateRange: {
+      label: 'Date range',
+      type: 'date-range'
+    }
+  },
+  sorts: {
+    newest: { label: 'Newest' },
+    oldest: { label: 'Oldest' }
+  },
+  searchPlaceholder: 'Search...'
+}
+
+// =============================================================================
+// Negative cases
+// =============================================================================
+
+declare function checkLocalization(l: MyLocalization): void
+
+// Missing a required filter key
+checkLocalization({
+  // @ts-expect-error — 'dateRange' is missing from filters
+  filters: {
+    status: { label: 'Status', options: [{ label: 'Active', value: 'active' }] }
+  },
+  sorts: { newest: { label: 'Newest' }, oldest: { label: 'Oldest' } }
+})
+
+// Missing a required sort key
+checkLocalization({
+  filters: {
+    status: { label: 'Status', options: [{ label: 'Active', value: 'active' }] },
+    dateRange: { label: 'Date range', type: 'date-range' }
+  },
+  // @ts-expect-error — 'oldest' is missing from sorts
+  sorts: { newest: { label: 'Newest' } }
+})
+
+// Wrong option value type — status options must use StatusValue
+checkLocalization({
+  filters: {
+    status: {
+      label: 'Status',
+      // @ts-expect-error — 'unknown' is not assignable to StatusValue
+      options: [{ label: 'Unknown', value: 'unknown' }]
+    },
+    dateRange: { label: 'Date range', type: 'date-range' }
+  },
+  sorts: { newest: { label: 'Newest' }, oldest: { label: 'Oldest' } }
+})
+
+// Wrong filter form — dateRange requires DateRangeTableFilter, not DefaultTableFilter
+checkLocalization({
+  filters: {
+    status: { label: 'Status', options: [{ label: 'Active', value: 'active' }] },
+    dateRange: {
+      label: 'Date range',
+      // @ts-expect-error — select-style options array is not valid for date-range filter
+      options: [{ label: 'Last 7 days', value: 'last7' }]
+    }
+  },
+  sorts: { newest: { label: 'Newest' }, oldest: { label: 'Oldest' } }
+})
+
+// =============================================================================
+// TableContainer generic inference — localization is derived from table type
+// =============================================================================
+
+type InferredLocalization<T extends StandardTable> = TableLocalization<
+  ReturnType<T['getFilterConfig']>,
+  ReturnType<T['getSortConfig']>
+>
+
+// Inferred localization from MyTable matches the manually specified one
+type _Inferred = Expect<Equal<InferredLocalization<MyTable>, MyLocalization>>
+
+// A table with no filters/sorts infers empty objects
+type EmptyTable = StandardTable<{}, {}>
+type EmptyLocalization = InferredLocalization<EmptyTable>
+type _EmptyFilters = Expect<Equal<EmptyLocalization['filters'], {}>>
+type _EmptySorts = Expect<Equal<EmptyLocalization['sorts'], {}>>