{"_id":"@cool-ai/beach-a2ui-basics","_rev":"4-43fed9b4a724ffa1778c647e25607519","name":"@cool-ai/beach-a2ui-basics","dist-tags":{"latest":"0.1.1"},"versions":{"0.0.1":{"name":"@cool-ai/beach-a2ui-basics","version":"0.0.1","license":"Apache-2.0","_id":"@cool-ai/beach-a2ui-basics@0.0.1","maintainers":[{"name":"johncandrew","email":"johncandrew@yahoo.co.uk"}],"homepage":"https://cool-ai.org","bugs":{"url":"https://gitlab.com/johncandrew/beach/-/issues"},"dist":{"shasum":"4c55f9245c8d09e1a8ae0b33d7ab386e00a16594","tarball":"https://registry.npmjs.org/@cool-ai/beach-a2ui-basics/-/beach-a2ui-basics-0.0.1.tgz","fileCount":41,"integrity":"sha512-6ovAf+qFiPw2aAmvZGJDPDDIqUNQkmxbVAIPcnJ91KMQFqNqV4q+EcQpj6I/fnjJbYZoP/x34wbKLY1IAXEILQ==","signatures":[{"sig":"MEQCIGYyr9fwp3HZSdoHSEANY8QolSQFsCVugKRY2OqFbsgGAiBUW65ZxfiiLPInVLd+1l9Hi/LwTjYJFTUi1ho7PGbmhA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":307665},"type":"module","_from":"file:cool-ai-beach-a2ui-basics-0.0.1.tgz","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./tokens.css":"./src/tokens.css"},"scripts":{"dev":"tsc --project tsconfig.json --watch","test":"vitest run","build":"tsc --project tsconfig.json","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"johncandrew","email":"johncandrew@yahoo.co.uk"},"_resolved":"/tmp/d24457f4cdab8a34f9d893ca25aabd29/cool-ai-beach-a2ui-basics-0.0.1.tgz","_integrity":"sha512-6ovAf+qFiPw2aAmvZGJDPDDIqUNQkmxbVAIPcnJ91KMQFqNqV4q+EcQpj6I/fnjJbYZoP/x34wbKLY1IAXEILQ==","repository":{"url":"git+https://gitlab.com/johncandrew/beach.git","type":"git","directory":"packages/a2ui-basics"},"_npmVersion":"10.9.7","description":"Generic semantic primitives for A2UI v0.9 — extends `@a2ui/web_core`'s basic catalogue with Pill, Hero, Heading, Badge, Avatar, RatingStars, Price, Tag, EmptyState, Skeleton, CallToAction.","directories":{},"_nodeVersion":"22.22.2","dependencies":{"lit":"^3.0.0","zod":"^3.23.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.0.0","@a2ui/lit":"^0.9.3","happy-dom":"^15.0.0","typescript":"^5.5.0","@a2ui/web_core":"^0.9.2"},"peerDependencies":{"@a2ui/lit":"^0.9.0","@a2ui/web_core":"^0.9.0"},"_npmOperationalInternal":{"tmp":"tmp/beach-a2ui-basics_0.0.1_1777132125729_0.6767140219840788","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@cool-ai/beach-a2ui-basics","version":"0.0.2","license":"Apache-2.0","_id":"@cool-ai/beach-a2ui-basics@0.0.2","maintainers":[{"name":"johncandrew","email":"johncandrew@yahoo.co.uk"}],"homepage":"https://cool-ai.org","bugs":{"url":"https://gitlab.com/johncandrew/beach/-/issues"},"dist":{"shasum":"e0ba4e81629c52bf132a37ac17a04de721513a54","tarball":"https://registry.npmjs.org/@cool-ai/beach-a2ui-basics/-/beach-a2ui-basics-0.0.2.tgz","fileCount":44,"integrity":"sha512-Gzs0UH7qvoZbjNGvr8b31IJDXl3H4ZCJnAnbRjiYpL7uDZ4LR7YnqJvgj5PXcJynU2ALzV107LQUJstePNQCag==","signatures":[{"sig":"MEQCIG5yRv6iT6cJsyycpNzPBi9n9FE7AaHhBQAHMkdrGqCcAiA9M8iLL2V/YbvTSDC6eZ0hCTUc4EeJc+pDAkvRdmGQPg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":353907},"type":"module","_from":"file:cool-ai-beach-a2ui-basics-0.0.2.tgz","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./tokens.css":"./src/tokens.css"},"scripts":{"dev":"tsc --project tsconfig.json --watch","test":"vitest run","build":"tsc --project tsconfig.json","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"johncandrew","email":"johncandrew@yahoo.co.uk"},"_resolved":"/tmp/8c80219573383d3eebe889272bd15966/cool-ai-beach-a2ui-basics-0.0.2.tgz","_integrity":"sha512-Gzs0UH7qvoZbjNGvr8b31IJDXl3H4ZCJnAnbRjiYpL7uDZ4LR7YnqJvgj5PXcJynU2ALzV107LQUJstePNQCag==","repository":{"url":"git+https://gitlab.com/johncandrew/beach.git","type":"git","directory":"packages/a2ui-basics"},"_npmVersion":"10.9.7","description":"Generic semantic primitives for A2UI v0.9 — extends `@a2ui/web_core`'s basic catalogue with Pill, Hero, Heading, Badge, Avatar, RatingStars, Price, Tag, EmptyState, Skeleton, CallToAction.","directories":{},"_nodeVersion":"22.22.2","dependencies":{"lit":"^3.0.0","zod":"^3.23.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.0.0","@a2ui/lit":"^0.9.3","happy-dom":"^15.0.0","typescript":"^5.5.0","@a2ui/web_core":"^0.9.2"},"peerDependencies":{"@a2ui/lit":"^0.9.0","@a2ui/web_core":"^0.9.0"},"_npmOperationalInternal":{"tmp":"tmp/beach-a2ui-basics_0.0.2_1778003245294_0.08132898403329802","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@cool-ai/beach-a2ui-basics","version":"0.1.0","license":"Apache-2.0","_id":"@cool-ai/beach-a2ui-basics@0.1.0","maintainers":[{"name":"johncandrew","email":"johncandrew@yahoo.co.uk"}],"homepage":"https://cool-ai.org","bugs":{"url":"https://gitlab.com/johncandrew/beach/-/issues"},"dist":{"shasum":"48ef1c46a932b7d157520ab6c647bd4982b0551a","tarball":"https://registry.npmjs.org/@cool-ai/beach-a2ui-basics/-/beach-a2ui-basics-0.1.0.tgz","fileCount":52,"integrity":"sha512-CE+fbz2RiCICRbexCmm2kVIXDhaecCPl5kvlE80C45IZenV2AGhS24nMx5rmvup2OACwQaOpw2eI4SDpAQn4yQ==","signatures":[{"sig":"MEUCIQCAnFv+eto0/hDf5ovKVK0ovxdwlzlnUk/EIBYfCWlK4gIgZ7+6UbAxvxbzOiE7YUW5IvEE/TPWi5GeFknDa1rHu84=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":371406},"type":"module","_from":"file:cool-ai-beach-a2ui-basics-0.1.0.tgz","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./tokens.css":"./src/tokens.css"},"scripts":{"dev":"tsc --project tsconfig.json --watch","test":"vitest run","build":"tsc --project tsconfig.json","coverage":"vitest run --coverage","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"johncandrew","email":"johncandrew@yahoo.co.uk"},"_resolved":"/tmp/f584ff4d70b31eed24a9fa46bc6b0244/cool-ai-beach-a2ui-basics-0.1.0.tgz","_integrity":"sha512-CE+fbz2RiCICRbexCmm2kVIXDhaecCPl5kvlE80C45IZenV2AGhS24nMx5rmvup2OACwQaOpw2eI4SDpAQn4yQ==","repository":{"url":"git+https://gitlab.com/johncandrew/beach.git","type":"git","directory":"packages/a2ui-basics"},"_npmVersion":"10.9.8","description":"Generic semantic primitives for A2UI v0.9 — extends `@a2ui/web_core`'s basic catalogue with Pill, Hero, Heading, Badge, Avatar, RatingStars, Price, Tag, EmptyState, Skeleton, CallToAction.","directories":{},"_nodeVersion":"22.22.3","dependencies":{"lit":"^3.0.0","zod":"^3.23.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.0.0","@a2ui/lit":"^0.9.3","happy-dom":"^15.0.0","typescript":"^5.5.0","@a2ui/web_core":"^0.9.2","@cool-ai/beach-a2ui":"^0.5.2"},"peerDependencies":{"@a2ui/lit":"^0.9.0","@a2ui/web_core":"^0.9.0"},"_npmOperationalInternal":{"tmp":"tmp/beach-a2ui-basics_0.1.0_1779086714645_0.5419815144332178","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@cool-ai/beach-a2ui-basics","version":"0.1.1","description":"Generic semantic primitives for A2UI v0.9 — extends `@a2ui/web_core`'s basic catalogue with Pill, Hero, Heading, Badge, Avatar, RatingStars, Price, Tag, EmptyState, Skeleton, CallToAction.","license":"Apache-2.0","repository":{"type":"git","url":"git+https://gitlab.com/johncandrew/beach.git","directory":"packages/a2ui-basics"},"homepage":"https://cool-ai.org","bugs":{"url":"https://gitlab.com/johncandrew/beach/-/issues"},"type":"module","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./tokens.css":"./src/tokens.css"},"publishConfig":{"access":"public"},"dependencies":{"lit":"^3.0.0","zod":"^3.23.0"},"devDependencies":{"@a2ui/lit":"^0.9.3","@a2ui/web_core":"^0.9.2","happy-dom":"^15.0.0","typescript":"^5.5.0","vitest":"^2.0.0","@cool-ai/beach-a2ui-renderer-lit":"^0.5.5"},"peerDependencies":{"@a2ui/lit":"^0.9.0","@a2ui/web_core":"^0.9.0"},"scripts":{"build":"tsc --project tsconfig.json","dev":"tsc --project tsconfig.json --watch","test":"vitest run","coverage":"vitest run --coverage","test:watch":"vitest","typecheck":"tsc --noEmit"},"_id":"@cool-ai/beach-a2ui-basics@0.1.1","_integrity":"sha512-9Ig9rkrGhM175bg6W0icXkGUK1cS2g+gXgIk/NKTyP9mZ+5B/oHdaYTqXo+WKlfDE8wKhg+jiFknAcCr6xn4AQ==","_resolved":"/tmp/7f2a4309c3cd1f2e6c7fef345651a5e8/cool-ai-beach-a2ui-basics-0.1.1.tgz","_from":"file:cool-ai-beach-a2ui-basics-0.1.1.tgz","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-9Ig9rkrGhM175bg6W0icXkGUK1cS2g+gXgIk/NKTyP9mZ+5B/oHdaYTqXo+WKlfDE8wKhg+jiFknAcCr6xn4AQ==","shasum":"2261b75f92572dc3cc3139c575e3262bf6cbcc09","tarball":"https://registry.npmjs.org/@cool-ai/beach-a2ui-basics/-/beach-a2ui-basics-0.1.1.tgz","fileCount":52,"unpackedSize":368666,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHUOrR+Cs7qLnWjzftaq6DJGtDk+r2ICGRx1VGschX2JAiEAmAzOPuQ6+xJ+8hWeiTwEWMkKLhhuBb93VGTIGHNAg08="}]},"_npmUser":{"name":"johncandrew","email":"johncandrew@yahoo.co.uk"},"directories":{},"maintainers":[{"name":"johncandrew","email":"johncandrew@yahoo.co.uk"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/beach-a2ui-basics_0.1.1_1780677375952_0.3207021864158033"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-25T15:48:45.653Z","modified":"2026-06-05T16:36:16.215Z","0.0.1":"2026-04-25T15:48:45.854Z","0.0.2":"2026-05-05T17:47:25.468Z","0.1.0":"2026-05-18T06:45:14.799Z","0.1.1":"2026-06-05T16:36:16.087Z"},"bugs":{"url":"https://gitlab.com/johncandrew/beach/-/issues"},"license":"Apache-2.0","homepage":"https://cool-ai.org","repository":{"type":"git","url":"git+https://gitlab.com/johncandrew/beach.git","directory":"packages/a2ui-basics"},"description":"Generic semantic primitives for A2UI v0.9 — extends `@a2ui/web_core`'s basic catalogue with Pill, Hero, Heading, Badge, Avatar, RatingStars, Price, Tag, EmptyState, Skeleton, CallToAction.","maintainers":[{"name":"johncandrew","email":"johncandrew@yahoo.co.uk"}],"readme":"# @cool-ai/beach-a2ui-basics\n\nGeneric semantic primitives for A2UI v0.9 — extends `@a2ui/web_core`'s basic catalogue with cross-domain components like `Pill`, `Hero`, `Heading`, `Badge`, `Avatar`, `RatingStars`, `Price`, `Tag`, `EmptyState`, `Skeleton`, `CallToAction`.\n\n> **Home:** [cool-ai.org](https://cool-ai.org) · **Documentation:** [cool-ai.org/docs](https://cool-ai.org/docs)\n\n## What it is\n\nA2UI v0.9's basic catalogue ships structural primitives — `Card`, `Row`, `Text`, `List`, `Button`, `Image` — intentionally close to raw HTML. This package is the **generic semantic layer** above it: components every Beach consumer will reuse regardless of domain.\n\nSchema = contract; implementation = brand. Two consumers can implement the same `Pill` schema with totally different visuals; two agents emitting `Pill` to those consumers both render appropriately. The Beach catalogue is the agreed semantic vocabulary.\n\nDomain-specific components (`DestinationCard`, `TaskCard`, `EmailDigestCard`) belong in **consumer-owned catalogues** that compose Beach primitives. Beach is the cross-domain coordinator, not the domain expert.\n\n## Install\n\n```sh\nnpm install @cool-ai/beach-a2ui-basics @a2ui/lit @a2ui/web_core lit\n```\n\n## Quick start\n\n```ts\nimport { MessageProcessor } from '@a2ui/web_core/v0_9';\nimport { basicCatalog } from '@a2ui/web_core/v0_9/basic_catalog';\nimport { beachBasicsCatalog } from '@cool-ai/beach-a2ui-basics';\n\n// Importing the element file registers the custom element with the browser.\nimport '@cool-ai/beach-a2ui-basics';\n\n// Optional: import the default token palette.\nimport '@cool-ai/beach-a2ui-basics/tokens.css';\n\nconst processor = new MessageProcessor([basicCatalog, beachBasicsCatalog]);\n```\n\nThen emit the catalogue's components in your surface messages:\n\n```ts\n{ component: 'Pill', label: 'Recommended', intent: 'recommended', icon: '✦' }\n```\n\n## Components\n\n### `Pill`\n\nA small, rounded badge for status labels and category tags.\n\n| Prop | Type | Required | Notes |\n|------|------|----------|-------|\n| `label` | DynamicString | yes | Text inside the pill |\n| `intent` | DynamicString | no | `'neutral' \\| 'recommended' \\| 'success' \\| 'warning' \\| 'danger'`. Unknown values render with neutral defaults |\n| `icon` | DynamicString | no | Emoji, single character, or short text rendered before the label |\n| `class` | DynamicString | no | Pass-through HTML `class` attribute on the host element |\n\n**Theming surfaces:**\n\n- `::part(label)` — the inner label span\n- `::part(icon)` — the inner icon span (only present when `icon` is set)\n- HTML `class` attribute via the `class` schema prop\n- CSS custom properties: `--bca-pill-bg`, `--bca-pill-fg`, `--bca-pill-radius`, `--bca-pill-padding-block`, `--bca-pill-padding-inline`, `--bca-pill-gap`, `--bca-pill-font-size`, `--bca-pill-font-weight`, `--bca-pill-letter-spacing`, plus `--bca-pill-{recommended,success,warning,danger}-{bg,fg}`\n\n```css\n/* Brand override example */\n.brand-pill::part(label) {\n  text-transform: uppercase;\n  letter-spacing: 0.1em;\n}\n\nbca-pill[intent='recommended'] {\n  --bca-pill-recommended-bg: var(--my-brand-gold);\n  --bca-pill-recommended-fg: var(--my-brand-navy);\n}\n```\n\n### `Show`\n\nConditional rendering primitive for in-surface progressive disclosure. When `when` resolves truthy, the referenced child component renders; falsy, the slot renders empty. Re-evaluates on data-model changes; only the affected subtree re-renders.\n\n| Prop | Type | Required | Notes |\n|------|------|----------|-------|\n| `when` | DynamicBoolean | yes | Literal `true`/`false`, JSON-pointer path (`{ path: '/openSlug' }`), or function call returning boolean |\n| `child` | ComponentId | yes | The id of the child component to render when `when` is truthy. Must exist in the surface's components map (same convention as `Card.child`); referencing a non-existent id throws `A2uiStateError` |\n\nA2UI v0.9 has three other conditional-shaped primitives; `Show` fills the gap left by the others:\n\n| Situation | Use |\n|---|---|\n| Switch between N pre-defined states with tab chrome | `Tabs` (A2UI basic catalogue) |\n| Overlay reveal that takes over the screen | `Modal` (A2UI basic catalogue) |\n| Drill into a detail warranting a new `surfaceId` | `subsurface:open` (`@cool-ai/beach-protocol`) |\n| Progressive disclosure / data-bound section toggle within one surface | **`Show`** |\n\n```ts\n// Toggle a detail panel by data-model state.\n{ component: 'Show',\n  when: { path: '/expanded' },\n  child: 'detail-panel' }\n```\n\nThe host element uses `display: contents` so the conditional wrapper has no visual footprint — the rendered child sits in the parent's layout flow as if `<beach-show>` were not present.\n\n#### Architectural notes\n\n- **Single-catalog constraint.** A2UI v0.9 binds a surface to one catalog (set on `createSurface`). The renderer resolves every component against that single catalog. To combine `Show` from this catalogue with primitives from `@a2ui/web_core`'s basic catalogue in the same surface, the consumer needs to construct a merged catalog. Same constraint applies to every consumer catalogue, not just Show.\n\n- **Import order for server-side rendering.** Lit's `@customElement` decorator registers against the global `customElements` registry at decorator time. When using Beach's `renderToHtml` / `renderToText` from `@cool-ai/beach-a2ui/render-server`, the element modules must be imported AFTER `bootstrapServerRender()` has provisioned jsdom — otherwise the registration no-ops:\n\n  ```ts\n  import { renderToHtml, bootstrapServerRender } from '@cool-ai/beach-a2ui/render-server';\n\n  await bootstrapServerRender();\n  await import('@cool-ai/beach-a2ui-basics');  // dynamic import after bootstrap\n\n  const html = await renderToHtml(commands, { catalogs: [beachBasicsCatalog] });\n  ```\n\n  CAIB-243 will add a defensive validator that surfaces this as a loud error rather than silent-empty output.\n\n## Theming\n\nEvery CSS custom property is prefixed `--bca-*` (Beach Catalogue Atoms) so it coexists cleanly with `@a2ui/web_core`'s `--a2ui-*` tokens. Override at `:root`, on a parent element, or per-instance via the `class` prop.\n\nThe default token palette ships in [`tokens.css`](./src/tokens.css). Importing it gives consumers an opinionated-but-overridable starting point — neutral surfaces, an amber accent, soft status colours, system-font typography. Override any subset by setting the custom properties on `:root` (or a scoped parent) **after** importing the defaults.\n\n## Catalogue identifier\n\n```ts\nimport { BEACH_A2UI_BASICS_CATALOG_ID } from '@cool-ai/beach-a2ui-basics';\n// 'https://cool-ai.org/a2ui/v0.9/basics.json'\n```\n\nThe URL is the contract. Bumps:\n\n- The `/v0.9/` segment moves when A2UI itself upgrades to a new protocol version.\n- A trailing `/vN/` is added for schema-breaking changes within a protocol version.\n- Patch releases of this package do **not** change the URL.\n\nSame posture as JSON Schema `$id`.\n\n## Why this layering\n\nBeach owns the generic primitives so:\n\n- Every Beach application speaks the same semantic vocabulary; cross-agent rendering \"just works\" once consumers register this catalogue.\n- Domain-specific catalogues (TA's `DestinationCard`, PO's `TaskCard`) compose Beach primitives instead of reinventing them.\n- Brand customisation lives at the consumer side via tokens, parts, and class — not at the protocol or component level.\n\nSee [`https://cool-ai.org/docs/design-principles`](https://cool-ai.org/docs/design-principles) for the architectural framing.\n\n## Related\n\n- [`@cool-ai/beach-a2ui`](../a2ui/README.md) — the wider Beach A2UI surface (renderer, builders, types).\n- [`@a2ui/web_core`](https://www.npmjs.com/package/@a2ui/web_core) — the upstream A2UI framework.\n- [`@a2ui/lit`](https://www.npmjs.com/package/@a2ui/lit) — the Lit-based reference renderer.\n","readmeFilename":"README.md"}