afs-list is an AUP cross-device primitive, not a Web Device layout component and not a Web-only widget. It is one of the 18 names in AUP_PRIMITIVES and appears in every target's DeviceCaps.primitives map as native, webview, partial, or unsupported.
Contract
| Field | Value |
|---|---|
| Primitive name | afs-list |
| Layer | AUP cross-device primitive (AUP_PRIMITIVES) |
| Public status | experimental |
| Document capability | native (renderer present; data contract open) |
| Shared degradation chain | None |
| Author entry | AUP + source/fixture (layout, itemStyle, from / src) · container directive with static children |
| Document renderer / notes | renderer/primitives/afs-list.ts (static children; empty+src → “Loading…”; empty no src → “No items”) |
| Showcase evidence | list-basic.aup and related list-* pages (from "data/items") |
When to use
Declarative lists over AFS paths or packaged fixtures on interactive targets.
When not to use
Do not bind arbitrary AFS paths in public docs. Do not claim verified live list sampling without a read-only fixture origin.
Sample contract
| Field | Value |
|---|---|
| Purpose | Honest empty-state and static-children rendering on document |
| Boundaries | No write actions; no arbitrary AFS path; no frame bridge; not proof that a path resolves on this site |
| Author entry | Container directive :::afs-list{…} |
| Surface | Web Device document |
| Public status | experimental |
| Fallback / failure | No children + no src → “No items”; no children + src → “Loading…” (static) |
| Verification | Routes below · empty states only; path-backed live data still open |
Document sample (empty — no items)
Source:
:::afs-list{id="docs-prim-afs-list-empty" layout="list" itemStyle="row"}
:::Rendered:
Document sample (src without children — loading chrome)
This shows the static renderer’s loading empty state. It does not fetch an AFS path on this documentation site.
Source:
:::afs-list{id="docs-prim-afs-list-loading" layout="list" itemStyle="row" src="data/items"}
:::Rendered:
Document sample (static children)
Pre-populated children render as list items. This is not evidence of AFS list() resolution.
Source:
:::afs-list{id="docs-prim-afs-list-static" layout="list" itemStyle="row"}
Static row one — authored as document children, not fetched.
Static row two — still not an AFS path proof.
:::Rendered:
Static row one — authored as document children, not fetched.
Static row two — still not an AFS path proof.
Showcase list-basic binds afs-list to packaged data/items with no write action on the list itself — useful evidence for a future embedded sample with a dedicated read-only fixture origin. See Live examples: scope and contract (“What a list must add”).
Failure and limits
| Situation | Expected result |
|---|---|
Empty list, no src | “No items” empty chrome |
Empty list with src | “Loading…” static chrome (no fetch proof here) |
| Arbitrary AFS path on public docs | Out of contract |
| Expecting write / drop / mutate | Out of contract |
Verification evidence
| Item | Value |
|---|---|
| Baseline | 2026-08-09 · arc --version → 2.0.0-beta.28 |
| Capability row | docs/aup/capability-matrix.md (internal, non-routed) · afs-list |
| Implementation | renderer/primitives/afs-list.ts; caps device-caps.ts |
| Public routes | /en/docs/aup/primitives/afs-list/ · /zh/docs/aup/primitives/afs-list/ |
| Local run | arc service start --blocklet blocklets/arcblock --port 4900 · confirm empty / loading / static-children chrome |
| Accept | Empty states match; page states data contract open; no arbitrary path claim |
Evidence anchors
| Item | Value |
|---|---|
| Registry | packages/aup/src/aup-types.ts · AUP_PRIMITIVES |
| Document caps | providers/runtime/web-device/src/device-caps.ts · DEVICE_CAPS_DOCUMENT |
| Degradation | packages/aup/src/degradation.ts · DEGRADATION_CHAINS |
| Internal matrix | docs/aup/capability-matrix.md (internal, non-routed) |
| Taxonomy hub | Primitive taxonomy and evidence |
| Sample contract rules | Live examples: scope and contract |