# App Grid Agents: start with [Workspace for Agents](https://workspace.socra.com/solutions/agents.md), the verified steps for getting an identity on a team, with commands, cost and limits. Socra: Fill the roles your team needs with proactive AI teammates, each with its own computer, identity and role. Canonical: https://socra.design/composed-components/app-grid ## Governing rules [Building with Socra components](https://socra.design/agents.md) explains setup, consumption rules and verification. Semantic owner: Flash Module `ui-component-family-navigation` in Socra Cortex when available. It supplies current intent and prerequisite rules; the public API below supplies exact code names and values. Use published property names, not inspector labels. Composition and preview settings are not component props. Public styling escape hatches do not permit product-local presentation overrides. Open an app from a stable grid of recognizable icons and names. The host supplies apps, destinations, icons and authorized activity. App Grid owns equal responsive tracks, bounded labels, accessible names and link states. Status: partial. Uses published @socra/web-ui 0.0.502, including independent collection and item alignment. Canonical catalog and Home adoption verification are tracked internally. Library: @socra/web-ui ## Anatomy - AppGrid is a named list. Standard tracks fill the available width; variant="launcher" uses a centered icon grid. The compact-launcher variant brings larger icons closer to their labels in centered wrapping rows. Each adapts without consumer layout styles. alignment="start" positions the collection at the leading content edge. itemAlignment="center" keeps each name centered under its icon independently of the collection; omitting it preserves the previous treatment. - AppGridItem receives a full name, a recognizable non-interactive icon and a host-approved href. - Centered standard and launcher names wrap within two lines. Compact-launcher names and names with leading item alignment wrap in full. Guidance and activity captions wrap in full. The full name remains the link’s accessible name and native tooltip; full guidance remains its accessible description. - A canonical BadgeCount shows current authorized activity, visually capped at 99+. The accessible description retains the complete count. - Optional description supplies brief availability or Account guidance. Loading or unavailable activity shares the caption area and allows rows to grow for complete guidance. Compact-launcher omits the empty caption track when no guidance or status is present. - A missing destination or disabled item remains visible as an unavailable link with no href or keyboard stop. ## States - **Rest:** Apps retain equal geometry whether their names are short, long or unbroken. - **Hover:** Available links use the shared neutral hover treatment. - **Focus:** Tab reaches available links in reading order with a visible focus treatment. - **Pressed:** Enter or pointer activation follows the host-provided native destination. - **Selected:** An app launcher opens a destination; it does not expose a selected state. - **Disabled:** Unavailable destinations cannot navigate or receive keyboard focus. Their explanation remains readable. - **Loading:** Loading activity hides previous badge counts while keeping the app link usable. - **Error:** Unavailable activity is described without implying zero unread items or disabling a valid app destination. ## Motion The shared loading spinner honors reduced motion. Activity updates preserve the name, icon and tile geometry. ## Usage - Keep app availability separate from activity loading. A failed count should not stop someone opening an authorized app. - Supply only current, authorized counts. Presentation cannot establish access or selected Account context. - Use recognizable app icons. The host owns product identity; the grid does not maintain a product-name enumeration. ## Avoid - Do not invent destinations or unread counts. Missing destinations stay unavailable and unknown counts stay absent. - Do not repair tile geometry in a consumer. Responsive layout, badges and long-content behavior belong to this shared contract. ## Properties [Complete public API, including inherited properties and event signatures](https://socra.design/composed-components/app-grid/api.md) ### Setup - Use the host-selected compatible Socra theme provider and published component styles. Keep one compatible provider instance across shared packages. ### AppGrid Import: `import { AppGrid } from '@socra/web-ui/app-grid';` | Property | Type or permitted values | Default / omission | Required | Meaning and behavior | Inspector | | --- | --- | --- | --- | --- | --- | | `alignment` | `"center"`, `"start"` | `"center"` | no | Align the group, icons and complete labels with surrounding content. Center preserves the existing presentation. Start follows text direction. | Alignment | | `children` | `ReactNode` | Required input | yes | | Direct API | | `itemAlignment` | `"center"`, `"start"` | Omitted; no declared default | no | Align each icon and label independently of the collection. | Icon and label alignment | | `label` | `string` | Required input | yes | Names the collection for assistive technology. | Direct API | | `variant` | `"standard"`, `"launcher"`, `"compact-launcher"` | `"standard"` | no | Standard and launcher retain operational state geometry. Compact launcher is icon-first navigation with close, complete labels and centered partial rows. | Layout | ### AppGridItem Import: `import { AppGridItem } from '@socra/web-ui/app-grid';` | Property | Type or permitted values | Default / omission | Required | Meaning and behavior | Inspector | | --- | --- | --- | --- | --- | --- | | `activity` | `"loading"`, `"ready"`, `"unavailable"` | `"ready"` | no | Activity may be pending or unavailable while the app remains usable. | Direct API | | `description` | `string \| undefined` | Omitted; no declared default | no | Brief availability or Account-context guidance; the full text stays accessible. | Direct API | | `disabled` | `false`, `true` | `false` | no | | Direct API | | `href` | `string \| undefined` | Omitted; no declared default | no | The host owns authorization and the destination's Account context. | Direct API | | `icon` | `ReactNode` | Required input | yes | A recognizable, non-interactive app image or glyph. Shared glyphs use size="inherit". | Direct API | | `name` | `string` | Required input | yes | | Direct API | | `unreadCount` | `number \| undefined` | Omitted; no declared default | no | Show only an authorized, current count. Zero and invalid counts are hidden. | Direct API | ### Behavior and constraints - AppGrid layout/alignment apply to every item; itemAlignment is an explicit override. Disabled/missing destinations suppress activity/count display; unread count is only meaningful when ready. ### Inspector mappings | Setting | Initial preview value | Consumed code | | --- | --- | --- | | Layout | `standard` | AppGrid.variant | | Alignment | `center` | AppGrid.alignment | | Icon and label alignment | `inherit` | AppGrid.itemAlignment. "inherit" omits the property | | Apps shown | `5` | composition: Choose how many fixture AppGridItem children the collection contains. | | App name | `Atlas` | derived: Set name on the first fixture AppGridItem; the remaining apps provide comparison content. | | Guidance | `` | derived: Set description on the first fixture AppGridItem; the remaining apps provide comparison content. | | Activity | `ready` | derived: Set activity on the first fixture AppGridItem; the remaining apps provide comparison content. | | Unread count | `8` | derived: Convert the selected count to first AppGridItem unreadCount. | | Disabled | `false` | derived: Set disabled on the first fixture AppGridItem; the remaining apps provide comparison content. | | Destination available | `true` | composition: Include or omit the first app href; absence demonstrates an unavailable destination. | ## Example ```tsx import { appGrid } from '@socra/web-ui'; import BookIcon from '@socra/ui-web-icon/BookIcon'; } href="/atlas" unreadCount={8} /> } href="/research" activity="loading" /> } description="A destination is not available yet." /> ```