anentrypoint-design 0.0.340 → 0.0.342

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anentrypoint-design",
-  "version": "0.0.340",
+  "version": "0.0.342",
   "description": "247420 design system SDK — webjsx + modified ripple-ui, single-file ESM bundle for reproducible use of the AnEntrypoint design.",
   "type": "module",
   "main": "./dist/247420.js",
@@ -84,6 +84,8 @@
     "lint:ui-kits": "node scripts/generate-ui-kit-scaffolds.mjs --check",
     "tokens": "node scripts/generate-tokens-json.mjs",
     "tokens:doc": "node scripts/generate-tokens-json.mjs && node scripts/generate-theme-tokens-doc.mjs",
+    "docs:components": "node scripts/generate-component-docs.mjs",
+    "lint:component-docs": "node scripts/generate-component-docs.mjs --check",
     "generate:ui-kits": "node scripts/generate-ui-kit-scaffolds.mjs",
     "generate:preview-index": "node scripts/generate-preview-index.mjs",
     "a11y": "node scripts/a11y-audit.mjs",

package/src/components/chat.js

@@ -97,7 +97,7 @@ function renderPart(p, key) {
     });
 }
 
-export function ChatMessage({ role, who = 'them', avatar, text, parts, time, typing, key, aicat, reactions, receipt, name, streaming, actions, incomplete, stopped, flat }) {
+export function ChatMessage({ role, who = 'them', avatar, text, parts, time, typing, key, aicat, reactions, receipt, name, streaming, actions, incomplete, stopped, flat, error, onRetry }) {
     _stats.messages += 1;
     // Support legacy 'who' prop, prefer 'role' with mapping:
     //   'user'      -> 'you'   (right-aligned, accent bubble)
@@ -144,6 +144,15 @@ export function ChatMessage({ role, who = 'them', avatar, text, parts, time, typ
         typeof stopped === 'string' ? stopped : 'stopped — this turn was cancelled before it finished')];
     if (incomplete) bodyNodes = [...bodyNodes, h('div', { key: '_incomplete', class: 'chat-msg-notice is-incomplete', role: 'status' },
         typeof incomplete === 'string' ? incomplete : 'connection dropped mid-turn — the response may be incomplete')];
+    // Inline per-turn error: unlike a global toast, this pins the failure to
+    // the specific turn that failed (docstudio pattern) with a retry action
+    // right there instead of forcing the user to hunt for what broke.
+    if (error) bodyNodes = [...bodyNodes, h('div', { key: '_error', class: 'chat-msg-notice is-error', role: 'alert' },
+        h('span', {}, typeof error === 'string' ? error : 'this turn failed'),
+        onRetry ? h('button', {
+            type: 'button', class: 'chat-msg-retry-btn',
+            onclick: (e) => { e.preventDefault(); onRetry(e); },
+        }, 'retry') : null)];
     const reactionRow = reactions && reactions.length
         ? h('div', { class: 'chat-reactions' },
             ...reactions.map((r, i) => h('span', { class: 'rxn' + (r.you ? ' you' : ''), key: 'r' + i, 'aria-label': `${r.emoji} reaction (${String(r.count)} ${String(r.count) === '1' ? 'reaction' : 'reactions'})${r.you ? ' - you reacted' : ''}` },

package/src/components/content.js

@@ -6,6 +6,18 @@ import * as webjsx from '../../vendor/webjsx/index.js';
 import { Btn, Heading, Lede, Dot, Icon } from './shell.js';
 const h = webjsx.createElement;
 
+// Avatar — generic identity disc: an image when `src` resolves, else a
+// letter fallback derived from `name`/`fallback`. Kit previously only had
+// scoped one-offs (chat.js `.chat-avatar`, community.js `.cm-user-avatar`)
+// duplicating this same letter-fallback logic; this is the reusable version.
+export function Avatar({ name, src, fallback, size = 'md', key } = {}) {
+    const letter = fallback != null ? fallback
+        : (name ? String(name).trim().charAt(0).toUpperCase() || '?' : '?');
+    const cls = 'ds-avatar ds-avatar-' + size;
+    if (src) return h('img', { key, class: cls, src, alt: name || '', loading: 'lazy' });
+    return h('span', { key, class: cls, 'aria-hidden': !!name, role: name ? 'img' : undefined, 'aria-label': name || undefined }, letter);
+}
+
 export function Panel({ title, count, right, style = '', class: className = '', children, kind, id }) {
     const cls = 'panel' + (kind ? ' panel-' + kind : '') + (className ? ' ' + className : '');
     return h('div', { class: cls, style, id: id || null },

package/src/components/files.js

@@ -147,8 +147,8 @@ export function FileRow({ name, type = 'other', size, modified, code, onOpen, on
 // grid does not flash from a bare spinner to a full list (predictable perceived
 // perf, the file-manager feel). `rows` controls how many ghost rows render.
 export function FileSkeleton({ rows = 12 } = {}) {
-    return h('div', { class: 'ds-file-grid ds-file-skeleton', 'aria-hidden': 'true' },
-        ...Array.from({ length: Math.max(1, rows) }, (_, i) => h('div', { key: 'sk' + i, class: 'ds-file-row ds-file-row-skeleton' },
+    return h('div', { class: 'ds-file-grid ds-file-skeleton', role: 'status', 'aria-busy': 'true', 'aria-label': 'loading files' },
+        ...Array.from({ length: Math.max(1, rows) }, (_, i) => h('div', { key: 'sk' + i, class: 'ds-file-row ds-file-row-skeleton', 'aria-hidden': 'true' },
             h('span', { class: 'ds-skel ds-skel-icon' }),
             h('span', { class: 'ds-skel ds-skel-title' }),
             h('span', { class: 'ds-skel ds-skel-meta' })))

package/src/components/sessions.js

@@ -37,17 +37,24 @@ export function fmtDuration(ms) {
   return hrs + 'h ' + (m % 60) + 'm';
 }
 
-// ConversationList — the Claude-Desktop "Chats" column. Sessions grouped by a
-// caller-supplied group label, each row showing title/project, relative time,
-// agent badge, and a running/new-event indicator. Selecting a row switches the
-// active conversation.
-//
-//   sessions : [{ sid, title, project, agent, time, running, unread, rail }]
-//   selected : the active sid
-//   groups   : OPTIONAL [{ label, sids:[...] }] to bucket rows; else one flat list
-//   search   : { value, onInput, placeholder } inline filter (optional)
-//   onSelect(session), onNew() : intents
-//   emptyText, loading, error  : explicit states
+/**
+ * The Claude-Desktop "Chats" column. Sessions grouped by a caller-supplied
+ * group label, each row showing title/project, relative time, agent badge,
+ * and a running/new-event indicator. Selecting a row switches the active
+ * conversation.
+ *
+ * @param {Object} [props]
+ * @param {Array<{sid:*, title?:string, project?:string, agent?:string, time?:string, running?:boolean, unread?:boolean, rail?:string}>} [props.sessions=[]]
+ * @param {*} [props.selected] - the active sid.
+ * @param {Array<{label:string, sids:Array<*>}>} [props.groups] - OPTIONAL buckets for the rows; else one flat list.
+ * @param {{value:string, onInput:Function, placeholder?:string}} [props.search] - inline filter (optional).
+ * @param {Function} [props.onSelect] - onSelect(session).
+ * @param {Function} [props.onNew] - onNew().
+ * @param {string} [props.emptyText='No conversations yet']
+ * @param {boolean} [props.loading=false]
+ * @param {*} [props.error=null]
+ * @returns {*} webjsx vnode
+ */
 export function ConversationList({ sessions = [], selected, groups, search, caption,
                                    onSelect, onNew, newLabel = 'New chat',
                                    emptyText = 'No conversations yet', loading = false, error = null,
@@ -304,11 +311,27 @@ const STREAM_WORD = {
   lost: 'live stream offline — retrying…',
 };
 
-// The stop-all / stop-selected danger buttons are two-step (host-driven, the kit
-// is stateless): the first click fires onArmStop* so the host flips confirming*
-// true and re-renders; the armed button reads 'stop N sessions - press again'
-// and only THAT click fires the real onStopAll/onStopSelected. Hosts that wire
-// no onArmStop* keep the old single-click behavior.
+/**
+ * The live multi-session command center ("Live" dashboard).
+ *
+ * The stop-all / stop-selected danger buttons are two-step (host-driven, the
+ * kit is stateless): the first click fires onArmStop* so the host flips
+ * confirming* true and re-renders; the armed button reads 'stop N sessions -
+ * press again' and only THAT click fires the real onStopAll/onStopSelected.
+ * Hosts that wire no onArmStop* keep the old single-click behavior.
+ *
+ * @param {Object} [props]
+ * @param {Array<Object>} [props.sessions=[]] - session shape: `{ sid, realSid, title, agent, model, cwd, elapsedMs, counter, lastActivity, currentTool, status, stopping, external, isNew, cost, tokens }`.
+ * @param {Function} [props.onStop] - onStop(session).
+ * @param {Function} [props.onOpen] - onOpen(session).
+ * @param {Function} [props.onView] - onView(session).
+ * @param {Function} [props.onStopAll]
+ * @param {Function} [props.onStopSelected]
+ * @param {boolean} [props.confirmingStopAll=false]
+ * @param {boolean} [props.confirmingStopSelected=false]
+ * @param {'connected'|'connecting'|'lost'|'offline'} [props.streamState]
+ * @returns {*} webjsx vnode
+ */
 export function SessionDashboard({ sessions = [], onStop, onOpen, onView, onStopAll, onStopSelected,
                                    confirmingStopAll = false, confirmingStopSelected = false,
                                    onArmStopAll, onArmStopSelected,

package/src/components/shell.js

@@ -6,19 +6,54 @@ import * as webjsx from '../../vendor/webjsx/index.js';
 import { trapTab } from './overlay-primitives.js';
 const h = webjsx.createElement;
 
+/**
+ * The wordmark used in Topbar/AppShell headers.
+ *
+ * @param {Object} [props]
+ * @param {string} [props.name='247420'] - the brand text.
+ * @param {*} [props.leaf] - optional trailing breadcrumb-style leaf, rendered after a " / " separator.
+ * @returns {*} webjsx vnode
+ */
 export function Brand({ name = '247420', leaf } = {}) {
     return h('span', { class: 'brand' }, name,
         leaf ? h('span', { class: 'slash' }, ' / ') : null,
         leaf || null);
 }
 
+/**
+ * A small pill/tag label.
+ *
+ * @param {Object} props
+ * @param {string} [props.tone=''] - semantic color tone (empty = neutral).
+ * @param {'sm'|'md'|'lg'} [props.size='md']
+ * @param {boolean} [props.tag=false] - true renders a rectangular sentence-case variant for dense data (drops the all-caps pill styling). Orthogonal to tone.
+ * @param {*} props.children
+ * @returns {*} webjsx vnode
+ */
 export function Chip({ tone = '', size = 'md', tag = false, children }) {
-    // size: 'sm' | 'md' | 'lg'; tag=true -> rectangular sentence-case variant
-    // for dense data (drops the all-caps pill). Both are orthogonal to tone.
     const sizeCls = size === 'sm' ? ' chip--sm' : (size === 'lg' ? ' chip--lg' : '');
     return h('span', { class: 'chip' + sizeCls + (tag ? ' chip--tag' : '') + (tone ? ' tone-' + tone : '') }, children);
 }
 
+/**
+ * The standard button/link factory. Renders an `<a>` when `href` is given,
+ * otherwise a `<button>`.
+ *
+ * @param {Object} props
+ * @param {string} [props.href] - if present, renders as a link instead of a button.
+ * @param {'default'|'primary'|'ghost'|'danger'} [props.variant='default']
+ * @param {'sm'|'md'|'lg'} [props.size='md']
+ * @param {*} props.children
+ * @param {Function} [props.onClick]
+ * @param {string} [props['aria-label']]
+ * @param {boolean} [props.primary] - legacy alias for variant:'primary', kept for backward compatibility.
+ * @param {boolean} [props.ghost] - legacy alias for variant:'ghost'.
+ * @param {boolean} [props.danger] - legacy alias for variant:'danger'.
+ * @param {boolean} [props.disabled]
+ * @param {string} [props.class] - extra class name(s) appended to the generated class list.
+ * @param {*} [props.key]
+ * @returns {*} webjsx vnode
+ */
 export function Btn({ href, variant = 'default', size = 'md', children, onClick, 'aria-label': ariaLabel, primary, ghost, danger, disabled, class: className, key }) {
     // Support legacy primary/ghost props for backward compatibility, but prefer variant
     const resolvedVariant = variant !== 'default' ? variant : (primary ? 'primary' : (ghost ? 'ghost' : (danger ? 'danger' : 'default')));
@@ -576,24 +611,25 @@ function wsCollapsed(which, fallback) {
     return !!fallback;
 }
 
-// WorkspaceShell — a Claude-Desktop / cowork three-(or four-)column app shell.
-//
-//   rail   : the persistent left workspace nav (icon+label items, collapsible
-//            to icon-only). Pass the result of WorkspaceRail() or any vnode.
-//   sessions: an OPTIONAL second column (a conversation/session list) shown
-//            between the rail and the main content. Null hides it.
-//   main   : the primary content column (chat thread, files view, dashboard...).
-//   pane   : an OPTIONAL right context pane (per-conversation context, file
-//            preview...). Null hides it; collapsible when present.
-//   crumb  : an optional thin top chrome bar (breadcrumb + status), spanning
-//            the content area only (the rail has its own header).
-//   status : an optional footer.
-//   narrow : caller's isNarrow() — drives the mobile single-column collapse.
-//   railCollapsed / paneCollapsed : initial collapse (persisted state wins).
-//
-// Pure stateless chrome (props in, vnode out). Collapse is DOM-class + a
-// persisted flag, so the host does not have to thread collapse state through its
-// own store. Visual styling lives in app-shell.css (.ws-*).
+/**
+ * A Claude-Desktop / cowork three-(or four-)column app shell.
+ *
+ * Pure stateless chrome (props in, vnode out). Collapse is DOM-class + a
+ * persisted flag, so the host does not have to thread collapse state through
+ * its own store. Visual styling lives in app-shell.css (.ws-*).
+ *
+ * @param {Object} props
+ * @param {*} props.rail - the persistent left workspace nav (icon+label items, collapsible to icon-only). Pass the result of WorkspaceRail() or any vnode.
+ * @param {*} props.sessions - an OPTIONAL second column (a conversation/session list) shown between the rail and the main content. Null hides it.
+ * @param {*} props.main - the primary content column (chat thread, files view, dashboard...).
+ * @param {*} props.pane - an OPTIONAL right context pane (per-conversation context, file preview...). Null hides it; collapsible when present.
+ * @param {*} props.crumb - an optional thin top chrome bar (breadcrumb + status), spanning the content area only (the rail has its own header).
+ * @param {*} props.status - an optional footer.
+ * @param {boolean} props.narrow - caller's isNarrow() — drives the mobile single-column collapse.
+ * @param {boolean} props.railCollapsed - initial rail collapse (persisted state wins).
+ * @param {boolean} props.paneCollapsed - initial pane collapse (persisted state wins).
+ * @returns {*} webjsx vnode
+ */
 export function WorkspaceShell({ rail, sessions, main, pane, crumb, status, narrow,
                                  railCollapsed = false, paneCollapsed = false,
                                  railLabel = 'workspace navigation',

package/src/components.js

@@ -16,7 +16,7 @@ export {
     WorksList, WritingList, Manifesto, Section, PageHeader,
     Kpi, Sparkline, BarChart, Table, SearchInput, TextField, Select, EventList,
     HomeView, ProjectView, Form,
-    Spinner, Skeleton, Alert, FilterPills
+    Spinner, Skeleton, Alert, FilterPills, Avatar
 } from './components/content.js';
 
 export {

package/src/css/app-shell/kits-appended.css

@@ -372,3 +372,16 @@
   .ds-chat-layout { display: grid; grid-template-columns: minmax(0, 1fr) 280px; align-items: start; gap: var(--space-4); }
   .ds-chat-detail { display: block; position: sticky; top: 0; }
 }
+
+/* Avatar — generic identity disc primitive (content.js Avatar). Sized
+   variants mirror the existing chat-avatar/community-avatar footprints so
+   any consumer gets a consistent disc without duplicating the CSS. */
+.ds-avatar {
+  display: inline-flex; align-items: center; justify-content: center;
+  border-radius: 50%; background: var(--bg-3); color: var(--fg);
+  font-family: var(--ff-mono); font-weight: 600; text-transform: lowercase;
+  letter-spacing: 0.02em; user-select: none; flex-shrink: 0; object-fit: cover;
+}
+.ds-avatar-sm { width: 24px; height: 24px; font-size: 10px; }
+.ds-avatar-md { width: 36px; height: 36px; font-size: 12px; }
+.ds-avatar-lg { width: 48px; height: 48px; font-size: 15px; }