anentrypoint-design 0.0.341 → 0.0.342

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anentrypoint-design",
-  "version": "0.0.341",
+  "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/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',