@onereach/idw-ui-components 0.1.2-beta.7.0 → 0.2.0-beta.27.0

package/README.md

@@ -2,13 +2,21 @@
 
 > Shared IDW UI components and browser helpers. Consumed by `idw-ui`.
 
+Peer dependencies:
+
+- `vue` ^3.5
+- `@onereach/ui-components` >= 26.14
+- `@onereach/idw-markdown-renderer` >= 1.1 (used by `FeedMarkdownContent` / `FeedSkillContent`)
+
+The host app must load Onereach styles / Tailwind (`@onereach/styles`) so utility classes and design tokens resolve. Include this package in the host Tailwind `content` globs (for example `./node_modules/@onereach/idw-ui-components/dist/**/*.{js,mjs,cjs}`) so class names used by components are not purged.
+
 ## Installation
 
 ```bash
 pnpm add @onereach/idw-ui-components
 ```
 
-## Usage
+## Helpers
 
 ```typescript
 import { formatIdwSummary } from '@onereach/idw-ui-components';
@@ -16,3 +24,354 @@ import type { IdwSummary } from '@onereach/idw-contracts';
 
 const label = formatIdwSummary(summary satisfies IdwSummary);
 ```
+
+## SkillCard
+
+Presentational skill tile (sizes `xs` / `s` / `l`). Used by feeds and settings surfaces.
+
+```vue
+<script setup lang="ts">
+import { CardSize, SkillCard, type SkillCardData } from '@onereach/idw-ui-components';
+
+const skill = {
+  id: '1',
+  name: 'Vacation',
+  image: '/skill.png',
+  domain: 'HR',
+} satisfies SkillCardData;
+</script>
+
+<template>
+  <SkillCard
+    :skill="skill"
+    :size="CardSize.S"
+    @click="onOpen"
+  />
+</template>
+```
+
+## FeedItemBase
+
+Presentational shell for schema-driven feed items. It owns metadata, title, short description, feed-level controls, and expand/collapse. Body content is opaque via slots.
+
+```vue
+<script setup lang="ts">
+import { FeedItemBase } from '@onereach/idw-ui-components';
+</script>
+
+<template>
+  <FeedItemBase
+    id="feed-1"
+    title="Important meeting needs review"
+    short-content="Owner Strategy Review overlaps with your vacation."
+    timestamp="1 min ago"
+    timestamp-datetime="2026-08-07T12:00:00.000Z"
+    source="by Vacation Skill"
+  >
+    <template #body>
+      <!-- Markdown, HTML, skill body, or embedded app -->
+    </template>
+
+    <template #actions>
+      <!-- Domain actions such as Approve or Reschedule -->
+    </template>
+
+    <template #footer>
+      <!-- Optional feedback, comments, or additional context (shown while body is open) -->
+    </template>
+  </FeedItemBase>
+</template>
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `string` | — | Stable feed item id (used for a11y ids) |
+| `title` | `string` | — | Shell title (always visible) |
+| `shortContent` | `string` | — | Shell short description |
+| `timestamp` | `string` | — | Preformatted timestamp text |
+| `timestampDatetime` | `string` | — | Optional value for `<time datetime>` |
+| `source` | `string` | — | Source / author text |
+| `expandable` | `boolean` | `true` | Whether the expand control is shown |
+| `fullscreenControl` | `boolean` | `false` | Shows `open_in_full` inside default `#controls`; host owns overlay via `fullscreen` |
+| `mentionControl` | `boolean` | `true` | Shows `alternate_email` (mention) inside default `#controls` |
+| `isNew` | `boolean` | `false` | Attention shell (`primary-opacity-12`) vs settled shell (`surface-2`) |
+| `controlLabels` | `Partial<Record<FeedItemControl, string>> & { fullscreen?: string }` | Mention / Fullscreen | Optional localized tooltips |
+
+When `expandable` is `false`, the body is always shown and the expand button is hidden.
+
+Expand labels are fixed (`Show more` / `Show less`). The scrollable body uses `max-height: 37.875rem` by default.
+
+`FeedItemControl`: `'mention'`
+
+### Slots
+
+- `body` — rich / schema / app content (lazy-mounted on first expand, kept mounted while the item lives)
+- `actions` — domain action buttons (visible only while body is open; empty slot content is hidden)
+- `footer` — optional extra footer (visible only while body is open)
+- `controls` — override default controls entirely (including fullscreen when `fullscreenControl` is true)
+
+### Default controls
+
+The default `#controls` content includes mention (`alternate_email`) when `mentionControl` is true (default), and fullscreen when `fullscreenControl` is true. A custom `#controls` slot replaces both.
+
+```vue
+<!-- Localize built-in control tooltips -->
+<FeedItemBase
+  ...
+  :control-labels="{ mention: 'Згадати', fullscreen: 'На весь екран' }"
+/>
+```
+
+### Events
+
+- `update:expanded` — expanded state changed
+- `expand` / `collapse` — convenience events
+- `control-click` — `'mention'` from the default mention control
+- `fullscreen` — fullscreen control clicked; host should open its overlay (modal / route)
+
+### Body lifecycle
+
+The body slot mounts on the first expansion and stays mounted afterwards. Collapsing hides it with `v-show` so embedded apps / iframes are not destroyed automatically.
+
+## Feed type content (body slot)
+
+Four presentational bodies for feed types (`markdown` | `skill` | `html` | `file`). Use them inside `FeedItemBase` `#body`. `FeedMarkdownContent` / `FeedSkillContent` encapsulate `@onereach/idw-markdown-renderer` plus feed `styled-content` typography. `FeedSkillContent` renders the built-in `SkillCard` when `skill` is passed (optional `#skill` override remains for rare custom cards).
+
+```vue
+<script setup lang="ts">
+import {
+  FeedItemBase,
+  FeedMarkdownContent,
+  FeedSkillContent,
+  FeedHtmlContent,
+  FeedFileContent,
+  type SkillCardData,
+} from '@onereach/idw-ui-components';
+
+const skill = { id: '1', name: 'Vacation', image: '/s.png', domain: 'HR' } satisfies SkillCardData;
+</script>
+
+<template>
+  <FeedItemBase id="1" title="Markdown" short-content="…">
+    <template #body>
+      <FeedMarkdownContent :text="content" />
+    </template>
+  </FeedItemBase>
+
+  <FeedItemBase id="2" title="Skill" short-content="…">
+    <template #body>
+      <FeedSkillContent
+        :text="content"
+        :skill="skill"
+        start-skill-label="Open Skill"
+        @start-skill="onStartSkill"
+        @skill-click="onSkillClick"
+      />
+    </template>
+  </FeedItemBase>
+
+  <FeedItemBase id="3" title="HTML" :fullscreen-control="true" class="[&_.feed-item-base__body]:!max-h-none">
+    <template #body>
+      <FeedHtmlContent title="HTML" :content="html" />
+    </template>
+  </FeedItemBase>
+
+  <FeedItemBase id="4" title="File" :fullscreen-control="true" class="[&_.feed-item-base__body]:!max-h-none">
+    <template #body>
+      <FeedFileContent title="File" :src="fileUrl" />
+    </template>
+  </FeedItemBase>
+</template>
+```
+
+| Component | Feed type | Notes |
+|-----------|-----------|--------|
+| `FeedMarkdownContent` | `markdown` | Renders `text` via `OrWebMarkdownRender` + `styled-content` / body typography |
+| `FeedSkillContent` | `skill` | Built-in `SkillCard` via `skill` prop + markdown; optional `startSkillLabel` → `start-skill`; `skill-click` |
+| `FeedHtmlContent` | `html` | `srcdoc` iframe using the fixed `FEED_EMBED_SANDBOX`; `size`: `'list'` \| `'fill'` |
+| `FeedFileContent` | `file` | `src` iframe using the fixed `FEED_EMBED_SANDBOX`; same `size` prop |
+
+Shared helpers: `FEED_EMBED_SANDBOX`, `FEED_EMBED_SIZE_CLASS`, type `FeedEmbedSize`. The sandbox value is not configurable through component props. Html/file share an internal embed implementation; empty `src` / `srcdoc` renders nothing.
+
+## FeedList
+
+Scrollable list of discriminated `FeedListItem` rows. Each row is a `FeedItemBase` shell with the matching type body. Host owns data fetching, i18n, fullscreen modal, and list footer content (e.g. reactions / comments). Skill cards are rendered inside the toolkit when `item.skill` is set.
+
+```vue
+<script setup lang="ts">
+import { FeedList, type FeedListItem } from '@onereach/idw-ui-components';
+
+const items: FeedListItem[] = [
+  { id: '1', title: 'Hello', type: 'markdown', content: '**Hi**', shortContent: 'Preview' },
+  { id: '2', title: 'App', type: 'html', content: '<h1>App</h1>' },
+  { id: '3', title: 'Doc', type: 'file', fileUrl: 'https://example.com/a.html' },
+  {
+    id: '4',
+    title: 'Skill news',
+    type: 'skill',
+    content: 'Details…',
+    skillId: 'skill-1',
+    skill: { id: 'skill-1', name: 'Vacation', image: '/s.png', domain: 'HR' },
+    startSkillLabel: 'Open Skill',
+  },
+  {
+    id: '5',
+    title: 'Approval',
+    type: 'card',
+    source: {
+      templateId: 'approval',
+      data: { title: 'Time off', summary: 'Approve vacation.', requester: 'Ada' },
+    },
+  },
+];
+</script>
+
+<template>
+  <FeedList
+    class="h-full"
+    :items="items"
+    :loading="false"
+    :loading-more="false"
+    empty-label="No posts yet"
+    item-class="mx-md"
+    :control-labels="{ fullscreen: 'Open in fullscreen' }"
+    @reach-bottom="loadMore"
+    @fullscreen="openFullscreen"
+    @start-skill="openSkill"
+    @skill-click="openSkillOverview"
+    @action="onCardAction"
+  >
+    <template #header>
+      <!-- Optional host header -->
+    </template>
+
+    <template #footer="{ item }">
+      <!-- Host reactions / comments (shown only while expanded) -->
+    </template>
+  </FeedList>
+</template>
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `FeedListItem[]` | — | Discriminated rows to render |
+| `loading` | `boolean` | `false` | Replaces the list with a loader |
+| `loadingMore` | `boolean` | `false` | Footer loader under existing items |
+| `emptyLabel` | `string` | `No posts yet` | Shown when `items` is empty (unless `#empty`) |
+| `controlLabels` | `FeedItemControlLabels` | — | Shared shell control tooltips |
+| `reachBottomOffset` | `number` | `500` | Px from bottom; `reach-bottom` is edge-triggered |
+| `itemClass` | `string` | — | Extra class on each `FeedItemBase` |
+| `cardHostConfig` | `Partial<IdwCardHostConfig>` | — | Theme / embed size for `type: 'card'` rows |
+
+`FeedListItem` is a discriminated union on `type`:
+
+- `markdown` / `html` — require `content: string`
+- `skill` — requires `content: string`; optional `skill` (`SkillCardData`) for the built-in card
+- `file` — requires `fileUrl: string`
+- `card` — requires `source` (`{ card }` or `{ templateId, data }`). Do not add `approval` / `task` as extra `type`s.
+- Shell fields are picked from `FeedItemBaseProps` (`timestampDatetime`, `fullscreenControl`, `mentionControl`, `isNew`, …)
+- Optional `engagement` (`FeedItemEngagement`) drives the built-in meta footer (reactions / comments / reading time) at the end of an **expanded** item
+
+HTML/file rows get `fullscreenControl` by default and an unconstrained body max-height.
+`mentionControl` defaults to `true` when omitted.
+
+### Slots
+
+- `header` — above the scroll region
+- `actions` / `controls` / `footer` — scoped `{ item }`, forwarded to `FeedItemBase` (`#footer` is shown only while the item body is open — use for reactions / comments)
+- `empty` / `loading` / `loading-more` — replace defaults
+
+### Events
+
+- `reach-bottom` — crossed into the near-end scroll zone (host loads next page)
+- `fullscreen` / `start-skill` / `skill-click` / `control-click` / `expand` / `collapse` — item payloads
+- `action` — `(item, event)` from a `type: 'card'` row (`verb`, `inputs`, …). Host performs the side effect.
+- `update:item-expanded` — `(item, expanded)` when a row expand state changes
+
+## IDW Cards
+
+Schema-driven body documents for feed items, canvas, and other hosts. This is **not** Adaptive Cards. `FeedItemBase` / `FeedList` stay host chrome (envelope). `CardRenderer` renders **body + actions** only.
+
+The `idw.card` schema and authoring skill live in [`@onereach/idw-contracts`](../contracts). Agents that **author** card JSON (or `templateId` + data) should follow [`../contracts/skills/idw-card-authoring/SKILL.md`](../contracts/skills/idw-card-authoring/SKILL.md). Hosts that **render** cards use `CardRenderer` below. This package re-exports the schema so existing imports keep working.
+
+Three layers:
+
+| Layer | Role |
+|---|---|
+| Card schema (`idw.card` / `1.0`) | Allowed elements, actions, nesting, and URLs |
+| Template | A reusable card document with `${path}` / `$when` bindings |
+| Template data schema | Domain payload for that template (e.g. approval) |
+
+The card JSON has no theme or raw colors. The host passes `hostConfig.theme` (`dark` default). Surfaces always use paired light + `dark:` token classes.
+
+```vue
+<script setup lang="ts">
+import {
+  CardRenderer,
+  cardFromMarkdown,
+  type IdwCardActionEvent,
+} from '@onereach/idw-ui-components';
+
+function onAction(event: IdwCardActionEvent) {
+  // host owns approve / reject / start-skill / …
+}
+</script>
+
+<template>
+  <CardRenderer
+    :source="{
+      templateId: 'approval',
+      data: {
+        title: 'Time off',
+        summary: 'Approve vacation next Friday.',
+        requester: 'Ada Lovelace',
+        dueAt: 'Friday',
+      },
+    }"
+    @action="onAction"
+  />
+
+  <CardRenderer :source="{ card: cardFromMarkdown('**Hello**') }" />
+</template>
+```
+
+### v1 elements
+
+Layout / content: `Text` (Markdown), `Image`, `ImageSet`, `FactSet`, `Container`, `ColumnSet` (2–3 columns), `Table`, `Media`, `Html`, `File`, `Skill`, `ActionSet`, `Badge`, `Icon`, `Progress`.
+
+Inputs (inspired by Adaptive Cards `Input.*`, plus IDW widgets). Every input has `name` (collected on action), plus optional `label`, `hint`, `required`, `errorMessage`, `disabled`:
+
+| Type | Renders as | Notes |
+|---|---|---|
+| `Input.Text` | `OrInputV3` / `OrTextareaV3` | `multiline`, `style`: text/email/url/tel/password |
+| `Input.Number` | `OrInputV3` | `min` / `max` / `step` |
+| `Input.Toggle` | `OrSwitchV3` | boolean |
+| `Input.Checkbox` | `OrCheckboxV3` | boolean |
+| `Input.ChoiceSet` | select / radio / checkbox group | `style`: compact / expanded / filtered; `multi` |
+| `Input.Date` | `OrDatePickerV3` | ISO date string |
+| `Input.Time` | `OrTimePickerV3` | `HH:mm` |
+| `Input.DateTime` | `OrDateTimePickerV3` | ISO datetime |
+| `Input.Slider` | `OrSliderV3` | number |
+| `Input.Range` | `OrRangeSliderV3` | `[from, to]` |
+| `Input.Rating` | `OrRatingV3` | number |
+| `Input.Location` | address (+ optional lat/lng) | `{ address, lat?, lng? }` |
+
+Spacing: `none | xs | sm | md | lg | xl`. Text style: `caption | body | headline`. Tone: `default | emphasis | success | warning | attention`.
+
+This is **not** Adaptive Cards JSON. We borrowed the input/container/action model (including ChoiceSet, Table, Media, ImageSet, ShowCard, ToggleVisibility) and mapped it onto or-components.
+
+Not in v1 (AC/Copilot extras we skipped on purpose): Refresh, Authentication, Carousel, Charts, `Data.Query` remote choices, `selectAction`, `RichTextBlock` runs, and `Action.Execute`. `Input.Location` has no or-component — it is address text plus optional lat/lng, not a map picker.
+
+### Closed actions
+
+`open-url`, `approve`, `reject`, `submit`, `start-skill`, `mention`, `open-conversation`, `toggle-visibility` (`targetIds`), `show-card` (`card`).
+
+`CardRenderer` emits `action` `{ verb, title, data?, url?, skillId?, targetIds?, card?, inputs? }` and forwards `skill-click`. `approve` / `reject` / `submit` validate required inputs first and attach the current `inputs` map. The host performs the side effect.
+
+Helpers: `cardFromMarkdown`, `cardFromHtml`, `cardFromFile`, `cardFromSkill`, `validateIdwCard`, `bindIdwCard`, `resolveCardRendererSource`.
+
+Html/file embeds reuse `FEED_EMBED_SANDBOX` and it is not configurable from the card.