#Catalog

Catalog provides a page-level skeleton for large capability collections that need search and filtering. Use it only when discovering and choosing a capability is the primary task; use a regular list or Resource Grid for small collections.

npm install @a3s-lab/ui@0.4.0

<section class="catalog" aria-labelledby="capability-catalog-title">
  <header>
    <div data-catalog-identity>
      <h1 id="capability-catalog-title">Capabilities</h1>
      <p>Find reusable skills, connectors, and work templates.</p>
    </div>
    <div data-catalog-actions>
      <label for="capability-search">Search capabilities</label>
      <input
        class="input"
        id="capability-search"
        type="search"
        placeholder="Search by name or purpose"
      />
    </div>
  </header>
  <div data-catalog-toolbar>
    <div data-catalog-filters aria-label="Capability type"></div>
    <div data-catalog-actions>
      <output data-catalog-count>12 capabilities</output>
    </div>
  </div>
  <div data-catalog-results aria-label="Capability results"></div>
</section>

import "@a3s-lab/ui/a3s.css";
import "@a3s-lab/ui/all";

#Usage

The Catalog root owns page arrangement only. The host implements search, filtering, sorting, installation, and data requests. Compose Resource Card, a list, or a table inside the results region.

<section class="catalog" aria-labelledby="capability-catalog-title">
  <header>
    <div data-catalog-identity>
      <h1 id="capability-catalog-title">Capabilities</h1>
      <p>Find reusable skills, connectors, and work templates.</p>
    </div>
    <div data-catalog-actions>
      <label for="capability-search">Search capabilities</label>
      <input
        class="input"
        id="capability-search"
        type="search"
        placeholder="Search by name or purpose"
      />
    </div>
  </header>
  <div data-catalog-toolbar>
    <div data-catalog-filters aria-label="Capability type"></div>
    <div data-catalog-actions>
      <output data-catalog-count>12 capabilities</output>
    </div>
  </div>
  <div data-catalog-results aria-label="Capability results"></div>
</section>

#Parameters

#States and variants

ready displays stable results. loading retains the title, filters, and results dimensions. empty explains why the current conditions match nothing and offers a clear-filter path. error names the failure and recovery. partial indicates pagination or that more results are still loading.

<section class="catalog" data-state="empty" aria-labelledby="empty-catalog-title-en">
  <header>
    <div data-catalog-identity><h2 id="empty-catalog-title-en">Capabilities</h2><p>No results match the current filters.</p></div>
  </header>
  <div data-catalog-toolbar>
    <div data-catalog-filters><span class="badge" data-variant="outline">Research · Installed</span></div>
    <div data-catalog-actions><output data-catalog-count aria-live="polite">0 capabilities</output></div>
  </div>
  <div data-catalog-results>
    <div class="empty" data-state="empty">
      <h3>No matching capabilities</h3>
      <p>Clear the Installed filter or try a broader search term.</p>
      <footer><button type="button" class="btn" data-variant="outline">Clear filters</button></footer>
    </div>
  </div>
</section>

Featured content is not a permanent advertising slot. Keep the set small and explainable. On phones, show complete stacked items instead of clipped horizontal cards that compete with primary results. Different resource types share search and selection rules; visible metadata communicates the type difference.

#Accessibility

Catalog needs one unique page title. Give the search input a visible or visually hidden label, and express filter selection with aria-pressed or equivalent semantics. Announce result count changes through data-catalog-count without moving focus or resetting scroll. Loading, empty, and error states retain title and filter context; retrying or clearing filters leaves focus on the triggering control. Featured and result items use real links or buttons—never a clickable card containing nested actions. The host owns queries, pagination, recommendation criteria, installation permissions, and trusted metadata; the component owns information architecture and responsive arrangement.