Cards

kai-cards

Drop in <kai-cards> to render a live stream of AI-generated card envelopes — confirmations, task lists, choice pickers, link previews, and custom types — while a single policy object routes every user action back to your app.

• Shadow DOM
• Property-driven API
• Built-in card types
• Extensible type registry
• CardFallback for unknown types

Preview

When to use

Reach for <kai-cards> whenever your AI response includes structured interactions — a deployment confirmation, a multi-step plan, a list of options. Pass server envelopes into el.cards, wire el.policy to handle results, and the element takes care of rendering, routing, and resolved (read-only) states.

Usage

Set all three in JavaScript — they’re arrays and objects, so none work as HTML attributes:

<kai-cards id="cards"></kai-cards>

<script type="module">
  import '@kitn.ai/ui/elements';
  const el = document.getElementById('cards');

  el.cards = [
    { type: 'confirm', id: 'deploy', title: 'Deploy to production?',
      data: { body: 'Apply 3 migrations?', tone: 'warning',
              actions: [{ id: 'go', label: 'Deploy', style: 'primary', default: true },
                        { id: 'no', label: 'Cancel' }] } },
  ];

  el.policy = {
    onAction: (cardId, action, payload) => console.log('action', cardId, action, payload),
    onSubmit: (cardId, data) => console.log('submit', cardId, data),
    onOpen:   (url, target) => window.open(url, target === 'tab' ? '_blank' : '_self'),
    onError:  (cardId, message) => console.warn('card error', cardId, message),
  };
</script>

• cards — array of CardEnvelope objects: { type, id, data, title?, resolution? }. The type string selects which built-in child element renders the envelope.
• policy — { onAction, onSubmit, onOpen, onDismiss, … }. Provide only the handlers your app needs; the rest are silently ignored. Swap it after mount — it is read at event time.
• types — { 'my-type': 'my-card-element' } merges over the built-in registry; override a built-in by reusing its key.
• Resolved cards — set resolution on an envelope ({ kind: 'action', action, payload? } or { kind: 'submit', data }) to render it in its read-only state after the user has acted.

Examples

Mixed Card Stream

Code

Single Confirm Card

Code

Resolved Card

Pass resolution on an envelope to lock it in its read-only view — useful when rehydrating conversation history.

Code

Unknown Type Fallback

Code

Props

Property	Type	Default	Notes
cards	{ … }[]	—	The stream of card envelopes to render. Set as a JS PROPERTY: `el.cards = [...]`.
types	Record<string, string>	—	Optional type→tag overrides/additions (merged over the built-ins). Property: `el.types`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type.
policy	{ … }	—	Optional CardPolicy handling child events. Property: `el.policy`.

Composed from

This element wraps these SolidJS components — reach for them directly when you need finer control than the props expose.

CardFallback

---

Need a hand? Report a bug Ask for help