openapi: 3.1.0
info:
  title: Filament Filter State Standardization Contract
  version: 1.0.0
  description: |
    Page-level contract for standardized Filament list filter behavior affected by Spec 126.
    This feature does not add public APIs. It formalizes the expected query-state,
    persistence, and filtering behaviors for in-scope resource list pages.
paths:
  /admin/{listSlug}:
    get:
      summary: Render a workspace-scoped Filament list with standardized filter behavior
      operationId: getWorkspaceScopedFilteredList
      tags:
        - Filament Filter UX
      parameters:
        - $ref: '#/components/parameters/ListSlug'
        - $ref: '#/components/parameters/TableSearch'
        - $ref: '#/components/parameters/TableSortColumn'
        - $ref: '#/components/parameters/TableSortDirection'
        - $ref: '#/components/parameters/TableFilters'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: Filtered list page rendered successfully
          content:
            text/html:
              schema:
                type: string
        '403':
          description: Actor is a member of the scope but lacks the capability required for page actions
        '404':
          description: Workspace scope is unavailable or the actor is not entitled to the requested scope
  /admin/t/{tenant}/{listSlug}:
    get:
      summary: Render a tenant-scoped Filament list with standardized filter behavior
      operationId: getTenantScopedFilteredList
      tags:
        - Filament Filter UX
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: string
          description: Tenant identifier resolved by existing Filament tenant route binding
        - $ref: '#/components/parameters/ListSlug'
        - $ref: '#/components/parameters/TableSearch'
        - $ref: '#/components/parameters/TableSortColumn'
        - $ref: '#/components/parameters/TableSortDirection'
        - $ref: '#/components/parameters/TableFilters'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: Tenant-scoped filtered list page rendered successfully
          content:
            text/html:
              schema:
                type: string
        '403':
          description: Tenant member lacks capability required for the page or exposed actions
        '404':
          description: Tenant or workspace context is unavailable or the actor is not entitled to the tenant scope
components:
  parameters:
    ListSlug:
      name: listSlug
      in: path
      required: true
      schema:
        type: string
      description: Logical list identifier for an in-scope Filament resource list
    TableSearch:
      name: tableSearch
      in: query
      required: false
      schema:
        type: string
      description: Free-text table search across approved searchable fields
    TableSortColumn:
      name: tableSortColumn
      in: query
      required: false
      schema:
        type: string
      description: Currently selected sort column
    TableSortDirection:
      name: tableSortDirection
      in: query
      required: false
      schema:
        type: string
        enum:
          - asc
          - desc
      description: Currently selected sort direction
    TableFilters:
      name: tableFilters
      in: query
      required: false
      style: deepObject
      explode: true
      schema:
        type: object
        additionalProperties: true
      description: |
        Native Filament filter state, including status, outcome, platform, policy_type,
        stale, archived, and date-range inputs such as `from` and `until`.
    Page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
      description: Current paginator page
  schemas:
    ResourceFilterProfile:
      type: object
      required:
        - persistence
        - archivedVisibility
        - centralStatusSource
      properties:
        persistence:
          type: object
          required:
            - search
            - sort
            - filters
          properties:
            search:
              type: boolean
            sort:
              type: boolean
            filters:
              type: boolean
        archivedVisibility:
          type: object
          properties:
            enabled:
              type: boolean
            label:
              type: string
              enum:
                - Archived
            placeholder:
              type: string
              enum:
                - Active
            trueLabel:
              type: string
              enum:
                - All
            falseLabel:
              type: string
              enum:
                - Archived
        centralStatusSource:
          type: object
          properties:
            required:
              type: boolean
            sourceKind:
              type: string
              enum:
                - enum
                - badge_catalog
                - tag_badge_catalog
                - config_registry
                - static_helper
        dateRange:
          type: object
          properties:
            enabled:
              type: boolean
            column:
              type: string
            indicatorSupport:
              type: boolean