@actioneer/ads 0.5.6 → 0.5.8

package/lib/spinner-mark.js

@@ -0,0 +1,98 @@
+"use client";
+import { jsx as s } from "react/jsx-runtime";
+const A = [
+  "action",
+  "content",
+  "upload",
+  "surface"
+], e = [0, 1, 2, 5, 8, 7, 6, 3], f = Array.from({ length: 9 }, (t, r) => ({
+  x: 1 + r % 3 * 5,
+  y: 1 + Math.floor(r / 3) * 5
+}));
+function m(t, r) {
+  return (t % r + r) % r;
+}
+const l = Array.from(
+  { length: e.length },
+  (t, r) => {
+    const n = new Array(9).fill(0.12);
+    n[4] = 0.26;
+    for (const o of [r, m(r + 4, e.length)])
+      n[e[o]] = 1, n[e[m(o - 1, e.length)]] = 0.68, n[e[m(o + 1, e.length)]] = 0.36;
+    return n;
+  }
+), h = [0, 1, 2, 1].map(
+  (t) => Array.from({ length: 9 }, (r, n) => {
+    const o = Math.floor(n / 3), i = n % 3, a = Math.abs(i - t);
+    return a === 0 ? o === 1 ? 1 : 0.78 : a === 1 ? 0.34 : 0.12;
+  })
+), d = [2, 1, 0, 1].map(
+  (t) => Array.from({ length: 9 }, (r, n) => {
+    const o = Math.floor(n / 3), i = n % 3, a = Math.abs(o - t);
+    return a === 0 ? i === 1 ? 1 : 0.78 : a === 1 ? 0.34 : 0.12;
+  })
+), p = [
+  [0.14, 0.34, 0.14, 0.34, 1, 0.34, 0.14, 0.34, 0.14],
+  [0.4, 1, 0.4, 1, 0.54, 1, 0.4, 1, 0.4],
+  [1, 0.56, 1, 0.56, 0.18, 0.56, 1, 0.56, 1],
+  [0.4, 1, 0.4, 1, 0.54, 1, 0.4, 1, 0.4]
+], g = {
+  action: { frames: l, duration: 1, staticFrame: 0 },
+  content: { frames: h, duration: 1.2, staticFrame: 1 },
+  upload: { frames: d, duration: 1.2, staticFrame: 0 },
+  surface: { frames: p, duration: 1.4, staticFrame: 0 }
+};
+function u(t) {
+  return Number(t.toFixed(3)).toString();
+}
+function y(t, r) {
+  return [...t.map((n) => n[r]), t[0][r]].map(u).join(";");
+}
+function F(t) {
+  return Array.from(
+    { length: t + 1 },
+    (r, n) => u(n / t)
+  ).join(";");
+}
+function M({ variant: t, className: r, ...n }) {
+  const o = g[t], i = F(o.frames.length);
+  return /* @__PURE__ */ s(
+    "svg",
+    {
+      viewBox: "0 0 16 16",
+      fill: "none",
+      shapeRendering: "geometricPrecision",
+      className: r,
+      ...n,
+      children: f.map((a, c) => /* @__PURE__ */ s(
+        "rect",
+        {
+          x: a.x,
+          y: a.y,
+          width: "4",
+          height: "4",
+          rx: "1.28",
+          fill: "currentColor",
+          opacity: o.frames[o.staticFrame][c],
+          children: /* @__PURE__ */ s(
+            "animate",
+            {
+              className: "motion-reduce:hidden",
+              attributeName: "opacity",
+              values: y(o.frames, c),
+              keyTimes: i,
+              dur: `${o.duration}s`,
+              repeatCount: "indefinite",
+              calcMode: "linear"
+            }
+          )
+        },
+        c
+      ))
+    }
+  );
+}
+export {
+  A as SPINNER_VARIANTS,
+  M as SpinnerMark
+};

package/llms.txt

@@ -11,6 +11,7 @@
    - `ToastProvider` (from `@actioneer/ads`) — required to render toasts
    - `<MotionConfig reducedMotion="user">` (from `motion/react`) — honor the OS reduced-motion setting
 4. Import contract: `import { Button } from "@actioneer/ads";` — the exact named export, never `@actioneer/ads/button`, never an alias, never a local copy.
+5. Motion contract: every imported component keeps its built-in ADS motion. For consumer-authored semantic state motion, import the matching named preset from `@actioneer/ads`; never copy raw spring values or introduce a separate timing system. Apply principle 3 on every component import/use change.
 
 ## Tokens
 
@@ -27,23 +28,24 @@ Reference semantic roles, never raw color/dimension literals (ads-lint rejects l
 - `muted-foreground`
 - `card`
 - `card-foreground`
-- `brand` — Brand (Sage green) — used for solid fills / primary actions, not body text
-- `brand-foreground` — Brand (Sage green) — used for solid fills / primary actions, not body text
-- `brand-hover` — Brand (Sage green) — used for solid fills / primary actions, not body text
-- `brand-text` — Brand (Sage green) — used for solid fills / primary actions, not body text
+- `brand` — Compatibility action role — neutral ink, never a colored primary hue.
+- `brand-foreground` — Compatibility action role — neutral ink, never a colored primary hue.
+- `brand-hover` — Compatibility action role — neutral ink, never a colored primary hue.
+- `brand-text` — Compatibility action role — neutral ink, never a colored primary hue.
 - `fill` — Quiet fill — secondary buttons, avatars, chips
 - `fill-foreground` — Quiet fill — secondary buttons, avatars, chips
 - `table-shell` — Quiet fill — secondary buttons, avatars, chips
+- `artifact-canvas`
 - `accent`
 - `accent-foreground`
-- `success`
-- `success-foreground`
-- `warning`
-- `warning-foreground`
-- `danger`
-- `danger-foreground`
-- `info`
-- `info-foreground`
+- `success` — success-700 on white = 5.48:1 (600 was 3.77:1, failed AA).
+- `success-foreground` — success-700 on white = 5.48:1 (600 was 3.77:1, failed AA).
+- `warning` — Amber-500 fill kept (it IS the caution signal); dark ink foreground
+- `warning-foreground` — Amber-500 fill kept (it IS the caution signal); dark ink foreground
+- `danger` — Amber-500 fill kept (it IS the caution signal); dark ink foreground
+- `danger-foreground` — Amber-500 fill kept (it IS the caution signal); dark ink foreground
+- `info` — Amber-500 fill kept (it IS the caution signal); dark ink foreground
+- `info-foreground` — Amber-500 fill kept (it IS the caution signal); dark ink foreground
 - `border-primary`
 - `border-secondary`
 - `border-tertiary`
@@ -71,21 +73,25 @@ Delineate SURFACES (cards, panels, sidebars, page regions) with color contrast,
 
 The single shadow-elevation token is an affordance: it goes ONLY on surfaces the user can act on. Never elevate something that can't be clicked. There is no shadow scale.
 
-- Do: Elevate actionable surfaces: pressable/hoverable cards, primary CTAs, control thumbs (Switch, Slider, active pills), and interactive floating layers (Modal, Drawer, Popover, Dropdown, listboxes, Toast).
+- Do: Elevate actionable surfaces: pressable/hoverable cards, primary CTAs, control thumbs (Switch, Slider, active tab segments), and interactive floating layers (Modal, Drawer, Popover, Dropdown, listboxes, Toast).
 - Do: Keep static surfaces flat: Panel, plain Card, Kbd, Navbar, headers, rails, docs boxes, Tooltip, InlineDrawer — they read by fill/color.
 - Do: Ask 'can the user click this surface?' — if no, it's flat.
 - Don't: Reintroduce a shadow scale (shadow-xs/sm/md/lg/xl) — there is one token only, shadow-elevation.
 - Don't: Put a shadow on a non-interactive surface for decoration.
 
-### 3. Motion follows the design-engineering guide [lint: unbounded-transition, sluggish-easing, zero-scale-entrance, undersized-zoom-entrance]
+### 3. Motion follows the interaction [lint: unbounded-transition, sluggish-easing, zero-scale-entrance, undersized-zoom-entrance, raw-spring-config]
 
-Every easing/duration/scale flows from a token (--ease-*, --duration-*, --scale-press), mirrored for Motion in src/lib/motion.ts. UI animations stay under 300ms, exits run faster than enters, and reduced motion is respected everywhere.
+Component motion follows the closest Animate UI interaction pattern, using role-specific presets defined in src/lib/motion.ts and exported from the ADS root barrel. Direct manipulation stays immediate, small CSS feedback stays local, and reduced motion is respected everywhere.
 
-- Do: Use strong curves only — the ease-out utility is the right default; overlays scale in origin-aware from their trigger.
-- Do: Give pressable elements a --scale-press on :active (text/link exempt); start entrances ≥ scale 0.95 with opacity.
-- Do: Respect reduced motion: keep opacity/color fades, drop movement.
-- Don't: Use a slow-starting (accelerating) easing on UI, an unbounded all-property transition, a scale-from-zero entrance, or a UI duration at or over 300ms.
+- Do: Treat motion as part of every ADS component import: preserve the component's built-in motion, and import any composition-level preset from the ADS root barrel.
+- Do: Map the component family before choosing motion: tabs/segments use control; checkbox/radio/switch use selection; menus use highlight; popovers/tooltips use overlay; modal/drawer use dialog/sheet; accordion/collapsible use disclosure; progress, carousel, and sidebar use their matching presets.
+- Do: Keep sliders, drag-resize, scrolling, and other pointer-following interactions immediate; motion begins after the committed value or destination changes.
+- Do: Give pressable elements local active feedback (text/link exempt); start entrances ≥ scale 0.95 with opacity.
+- Do: Wrap Motion components in MotionConfig reducedMotion='user'; keep useful opacity/color feedback and drop spatial movement.
+- Don't: Invent raw spring values inside a component, recreate a global duration/easing token scale, use an unbounded all-property transition, or start an entrance at scale zero.
+- Don't: Override or duplicate the motion already shipped inside an imported ADS component.
 - Don't: Animate keyboard-initiated or 100×/day actions (e.g. a command-palette toggle).
+- Don't: Add motion to a component only because it is visible; static structure and decorative chrome stay still.
 
 ### 4. Icons: Hugeicons, stroke only [lint: icon-package-import]
 
@@ -124,12 +130,13 @@ Every UI decision stays synchronized with ADS. Before making a new screen/contro
 
 ### 8. Minimal information per screen [judgment]
 
-A screen carries ONLY what the user needs to move forward: one title, at most one short supporting line, the inputs, one primary action. Never maximalist. Promote the one message that matters typographically instead of appending muted fine print.
+A screen carries ONLY what the user needs to move forward: one title, the inputs, one primary action. Page, section, panel, modal, dialog, drawer, and popover headers are title-only by default; add a description only when the user explicitly asks for one. Never maximalist.
 
 - Do: Prefer more, smaller steps over dense ones; ask one thing at a time.
 - Do: Derive instead of asking whenever possible (a name from a work email, the company from its domain).
 - Do: Render multi-step flows full-screen — a single content container that holds the inputs and its own Back/Continue is fine.
 - Don't: Add section eyebrows above a title that already names the screen, or helper text that restates the obvious / duplicates a disabled button's meaning.
+- Don't: Add any header description unless the user explicitly requested supporting copy for that page, section, panel, modal, dialog, drawer, or popover.
 - Don't: Nest panel/step-rail chrome inside a multi-step flow.
 
 ### 9. Responsive = container-fluid components, shells own the width [judgment]
@@ -163,12 +170,37 @@ When tabs and a search field control the same content, they share one responsive
 
 ## Components
 
+Before using any component below, preserve its built-in motion and apply the motion contract in Setup step 5.
+
 ### Primitives / utilities
 
 - [TooltipProvider] — component [docs](https://ads.actioneer.dev/#/tooltip)
 - [InteractiveProps] — TypeScript type
+- [backdropVariants] — utility
+- [checkDrawTransition] — utility
 - [cn] — utility
+- [drawerBackdropVariants] — utility
+- [drawerOffset] — utility
+- [fadeTransition] — utility
+- [floatVariants] — utility
 - [interactive] — utility
+- [menuVariants] — utility
+- [modalPanelVariants] — utility
+- [screenVariants] — utility
+- [springCarousel] — utility
+- [springControl] — utility
+- [springDialog] — utility
+- [springDisclosure] — utility
+- [springEffect] — utility
+- [springHighlight] — utility
+- [springOverlay] — utility
+- [springProgress] — utility
+- [springRadio] — utility
+- [springSheet] — utility
+- [springSidebar] — utility
+- [springSwitch] — utility
+- [toastVariants] — utility
+- [tooltipVariants] — utility
 
 ### Foundations
 
@@ -192,7 +224,7 @@ When tabs and a search field control the same content, they share one responsive
 - [ScrollBar] — component [docs](https://ads.actioneer.dev/#/review/scroll-area)
 - [SettingList] — component (variants: isPressable: true|false) [docs](https://ads.actioneer.dev/#/review/setting-row)
 - [SettingRow] — component (variants: isPressable: true|false) [docs](https://ads.actioneer.dev/#/review/setting-row)
-- [Spinner] — Use for an indeterminate loading state (e.g. inside a Button's isLoading, or standalone while content is fetching) — not for measurable/determinate progress. (variants: size: sm|md|lg; color: current|primary|muted) [docs](https://ads.actioneer.dev/#/spinner)
+- [Spinner] — Use the nine-squircle Spinner for indeterminate work; choose its variant by work scope and use Progress or ProgressCircle when completion can be measured. (variants: size: xs|sm|md|lg; color: current|primary|muted) [docs](https://ads.actioneer.dev/#/spinner)
 - [Stepper] — component (variants: status: complete|current|upcoming|error; size: sm|md) [docs](https://ads.actioneer.dev/#/review/stepper)
 - [Text] — Use Text for any body copy, caption, or inline run of prose instead of a raw p/span tag. [docs](https://ads.actioneer.dev/#/typography)
 - [Tooltip] — Use to label a single hover/focus-triggered element (icon-only buttons, avatars, truncated text) with a short informational hint — not for actions or content that needs to stay open. [docs](https://ads.actioneer.dev/#/tooltip)
@@ -214,6 +246,7 @@ When tabs and a search field control the same content, they share one responsive
 - [SettingListProps] — TypeScript type
 - [SettingRowProps] — TypeScript type
 - [SpinnerProps] — TypeScript type
+- [SpinnerVariant] — TypeScript type
 - [StepperProps] — TypeScript type
 - [StepperStatus] — TypeScript type
 - [StepperStep] — TypeScript type
@@ -224,6 +257,7 @@ When tabs and a search field control the same content, they share one responsive
 - [fileDropzoneVariants] — utility
 - [inputBaseClass] — utility
 - [settingRowVariants] — utility
+- [SPINNER_VARIANTS] — utility
 - [stepperMarkerVariants] — utility
 
 ### Form controls
@@ -236,7 +270,7 @@ When tabs and a search field control the same content, they share one responsive
 - [NumberField] — Use for a bounded numeric quantity (e.g. seats, width, count) that benefits from stepper buttons and min/max clamping, not free-form numeric text entry. [docs](https://ads.actioneer.dev/#/number-field)
 - [Radio] — Use for choosing exactly one option from a small, fully visible set — wrap Radio options in a RadioGroup that owns the shared name and controlled value. [docs](https://ads.actioneer.dev/#/radio)
 - [RadioGroup] — component [docs](https://ads.actioneer.dev/#/radio)
-- [SegmentedControl] — Use for a small set (2-4) of mutually exclusive, always-visible options — like a range or view-mode switcher — not for navigation or long lists. (variants: size: sm|md|lg; selected: true|false) [docs](https://ads.actioneer.dev/#/segmented)
+- [SegmentedControl] — Use for a small set (2-4) of mutually exclusive, always-visible options — like a range or view-mode switcher — not for navigation or long lists. Radius follows control size: 4px at sm and 8px at md/lg; tracks and options are never fully rounded. (variants: size: sm|md|lg; selected: true|false) [docs](https://ads.actioneer.dev/#/segmented)
 - [Select] — Use for a single choice from a closed list of options in a form, especially when pairing with Field for a labeled control. (variants: size: sm|md|lg) [docs](https://ads.actioneer.dev/#/select)
 - [Slider] — Use for a single controlled numeric value picked from a bounded range (volume, brightness, threshold) — pair with Field or Label/Text for an accessible, labeled control. [docs](https://ads.actioneer.dev/#/slider)
 - [Switch] — Use for a single binary on/off preference that applies immediately, not as part of a form submitted later. [docs](https://ads.actioneer.dev/#/switch)
@@ -311,6 +345,10 @@ When tabs and a search field control the same content, they share one responsive
 - [AccordionItem] — component [docs](https://ads.actioneer.dev/#/accordion)
 - [AnswerRenderer] — component (variants: tone: default|primary|success|warning|danger|info) [docs](https://ads.actioneer.dev/#/ai/answer)
 - [AnswerSkeleton] — component (variants: tone: default|primary|success|warning|danger|info) [docs](https://ads.actioneer.dev/#/ai/answer)
+- [AnswerSourceChip] — Use the blue connector/source chip inside AnswerSources to open only the referenced nodes represented by that chip in the shell's inspector. [docs](https://ads.actioneer.dev/#/ai/sources)
+- [AnswerSourceInspector] — Render as a separate white shell-level panel beside the answer when a source chip is selected; close and unmount it when the selection clears. [docs](https://ads.actioneer.dev/#/ai/sources)
+- [AnswerSourceItem] — Use as an outlined clickable row inside AnswerSourceInspector for one referenced table or node, including its parent source, read state, and optional status. [docs](https://ads.actioneer.dev/#/ai/sources)
+- [AnswerSources] — Place immediately above an answer's follow-up questions to summarize the referenced nodes and group them into clickable AnswerSourceChips. [docs](https://ads.actioneer.dev/#/ai/sources)
 - [AreaChart] — component [docs](https://ads.actioneer.dev/#/ai/chart)
 - [Avatar] — Use to represent a person or entity as a compact photo-or-initials glyph, standalone or stacked in an AvatarGroup. [docs](https://ads.actioneer.dev/#/avatar)
 - [AvatarGroup] — component [docs](https://ads.actioneer.dev/#/avatar)
@@ -376,7 +414,7 @@ When tabs and a search field control the same content, they share one responsive
 - [TableRow] — component [docs](https://ads.actioneer.dev/#/table)
 - [TabList] — component (variants: variant: primary|secondary|pill; orientation: horizontal|vertical; size: sm|md|lg) [docs](https://ads.actioneer.dev/#/tabs)
 - [TabPanel] — component (variants: variant: primary|secondary|pill; orientation: horizontal|vertical; size: sm|md|lg; selected: true|false) [docs](https://ads.actioneer.dev/#/tabs)
-- [Tabs] — Use Tabs to switch between mutually exclusive views/sections that share the same page context, not for page-level navigation. Always reach for the primary (pill) variant — it is the default; use secondary only when explicitly asked for it. When Tabs and a scoped search field coexist, compose one responsive control row with tabs leading and search trailing; do not stack search above tabs at widths where both fit. (variants: variant: primary|secondary|pill; orientation: horizontal|vertical; size: sm|md|lg; selected: true|false) [docs](https://ads.actioneer.dev/#/tabs)
+- [Tabs] — Use Tabs to switch between mutually exclusive views/sections that share the same page context, not for page-level navigation. Always reach for the primary recessed-track variant — it is the default; use secondary only when explicitly asked for it. Tab radius follows control size (4px sm, 8px md/lg), never rounded-full. When Tabs and a scoped search field coexist, compose one responsive control row with tabs leading and search trailing; do not stack search above tabs at widths where both fit. (variants: variant: primary|secondary|pill; orientation: horizontal|vertical; size: sm|md|lg; selected: true|false) [docs](https://ads.actioneer.dev/#/tabs)
 - [TabSeparator] — component (variants: variant: primary|secondary|pill; orientation: horizontal|vertical; size: sm|md|lg; selected: true|false) [docs](https://ads.actioneer.dev/#/tabs)
 - [Timeline] — Use for a vertical rail of dated events — version history, audit trails, activity/status feeds. [docs](https://ads.actioneer.dev/#/timeline)
 - [TimelineItem] — component [docs](https://ads.actioneer.dev/#/timeline)
@@ -396,6 +434,10 @@ When tabs and a search field control the same content, they share one responsive
 - [AnswerRendererProps] — TypeScript type
 - [AnswerSkeletonProps] — TypeScript type
 - [AnswerSource] — TypeScript type
+- [AnswerSourceChipProps] — TypeScript type
+- [AnswerSourceInspectorProps] — TypeScript type
+- [AnswerSourceItemProps] — TypeScript type
+- [AnswerSourcesProps] — TypeScript type
 - [AnswerSpec] — TypeScript type
 - [AnswerTone] — TypeScript type
 - [AreaChartProps] — TypeScript type
@@ -573,6 +615,7 @@ When tabs and a search field control the same content, they share one responsive
 - [ProgressCircle] — Use for a compact circular loading/progress indicator (determinate or indeterminate) where a linear bar doesn't fit, e.g. inline with a caption or a small avatar-sized control. [docs](https://ads.actioneer.dev/#/progress-circle)
 - [Ripple] — component [docs](https://ads.actioneer.dev/#/ripple)
 - [Skeleton] — Placeholder the shape of content that's still loading — size it via className and pair with circle for avatars. [docs](https://ads.actioneer.dev/#/skeleton)
+- [AgentIconColorPreset] — TypeScript type
 - [AgentIconName] — TypeScript type
 - [AgentIconProps] — TypeScript type
 - [AgentIconState] — TypeScript type
@@ -601,7 +644,7 @@ When tabs and a search field control the same content, they share one responsive
 - [NavbarItem] — component (variants: justify: start|center|end) [docs](https://ads.actioneer.dev/#/navbar)
 - [PageHeader] — Use for every page title row; supply onBack to anchor an icon-only back arrow immediately before the title, never in the trailing actions area. [docs](https://ads.actioneer.dev/#/page-header)
 - [Pagination] — Use for navigating multi-page numbered content — table footers, search results, or any list too long for one screen. [docs](https://ads.actioneer.dev/#/pagination)
-- [Sidebar] — Use as the app's left navigation rail — compose it from SidebarHeader/SidebarBrand, SidebarNav (sections of SidebarItems), optional SidebarHistory, and a SidebarFooter with SidebarAccount, with an opt-in collapsed icon-rail mode (⌘B/Ctrl-B) that every sub-part reads automatically. [docs](https://ads.actioneer.dev/#/sidebar)
+- [Sidebar] — Use as the app's left navigation rail. The canonical Actioneer shell composes SidebarBrand with persistent header actions, SidebarAction above grouped SidebarItems, optional attention counts and SidebarHistory, then SidebarAccount in a pinned footer. Its opt-in collapsed icon-rail mode (⌘B/Ctrl-B) is shared automatically by every sub-part. [docs](https://ads.actioneer.dev/#/sidebar)
 - [SidebarAccount] — component [docs](https://ads.actioneer.dev/#/sidebar)
 - [SidebarAction] — component [docs](https://ads.actioneer.dev/#/sidebar)
 - [SidebarBrand] — component [docs](https://ads.actioneer.dev/#/sidebar)
@@ -879,8 +922,8 @@ When tabs and a search field control the same content, they share one responsive
 - [FileName] — component [docs](https://ads.actioneer.dev/#/demo/ask)
 - [FileRoot] — component [docs](https://ads.actioneer.dev/#/demo/ask)
 - [FileSize] — component [docs](https://ads.actioneer.dev/#/demo/ask)
-- [FollowUpQuestion] — component [docs](https://ads.actioneer.dev/#/demo/ask)
-- [FollowUpSuggestion] — component [docs](https://ads.actioneer.dev/#/demo/ask)
+- [FollowUpQuestion] — Use for the two or three full-width next-question rows that close a structured answer, immediately after its source strip; show the exact prompt that clicking will send. [docs](https://ads.actioneer.dev/#/ai/follow-up-suggestions)
+- [FollowUpSuggestion] — Use only for compact runtime suggestion chips above the composer; use FollowUpQuestion for the larger answer-ending question rows. [docs](https://ads.actioneer.dev/#/ai/follow-up-suggestions)
 - [Image] — component [docs](https://ads.actioneer.dev/#/demo/ask)
 - [ImageActions] — component [docs](https://ads.actioneer.dev/#/demo/ask)
 - [ImageContentFilterError] — component [docs](https://ads.actioneer.dev/#/demo/ask)