@you-agent-factory/components 0.0.0 → 0.0.2

package/docs/widget-frame-recipes.md

@@ -1,273 +0,0 @@
-# Widget frame and layout recipes
-
-Domain-free widget frame shells and layout recipes for dashboard-like panels.
-Use these components when you need framed content regions with consistent
-typography, state treatments, disclosure controls, and responsive layout helpers
-without importing dashboard features, bento grids, API clients, or app state.
-
-## Required setup
-
-Import package styles once in your host application before rendering recipes:
-
-```css
-@import "@you-agent-factory/components/styles.css";
-```
-
-Recipes depend on package role tokens (`--color-surface`, `--shadow-af-card`,
-typography roles) and Tailwind utility classes compiled from those tokens. They
-do not require dashboard `styles.css`, dashboard providers, generated OpenAPI
-types, React Query, Zustand, or app localization context.
-
-## Import paths
-
-Prefer the recipes category entrypoint for tree-shaking and explicit category
-boundaries:
-
-```ts
-import {
-  WidgetFrame,
-  WidgetSubtitle,
-  WidgetDetailCopy,
-  WidgetEmptyState,
-  WidgetEmptyStateTitle,
-  WidgetEmptyStateText,
-  WidgetLoadingState,
-  WidgetErrorState,
-  WidgetSuccessState,
-  WidgetFrameDisclosure,
-  WidgetFrameDisclosureTrigger,
-  WidgetFrameDisclosurePanel,
-  widgetFrameDetailCardClass,
-} from "@you-agent-factory/components/recipes";
-```
-
-The same exports are also available from the package root:
-
-```ts
-import { WidgetFrame } from "@you-agent-factory/components";
-```
-
-## Host ownership
-
-The package owns presentation markup, layout classes, and accessibility
-semantics for frame shells. Host applications own everything domain-specific:
-
-| Concern | Owner |
-| --- | --- |
-| User-visible copy (titles, messages, labels) | Host |
-| Data fetching, caching, and error mapping | Host |
-| Domain models (factory, work, session, provider) | Host |
-| Collapsed/expanded boolean state | Host |
-| Header and body action callbacks | Host |
-| Bento grid composition, drag/resize, widget selection | Dashboard feature code |
-| Durable cross-route or persisted UI state | Host |
-
-Pass copy and state into recipe components as props and children. Do not expect
-recipes to read from your routers, stores, or API layers.
-
-## Composition overview
-
-A typical framed panel stacks:
-
-1. `WidgetFrame` — card shell with title, optional `headerAction`, and scrollable body.
-2. Content primitives — `WidgetSubtitle`, `WidgetDetailCopy`, or arbitrary host children.
-3. State shells — `WidgetLoadingState`, `WidgetErrorState`, `WidgetSuccessState`, or `WidgetEmptyState`.
-4. Optional disclosure — `WidgetFrameDisclosure` + controlled trigger/panel pair.
-
-```tsx
-import { useState } from "react";
-import {
-  WidgetDetailCopy,
-  WidgetEmptyStateText,
-  WidgetEmptyStateTitle,
-  WidgetFrame,
-  WidgetFrameDisclosure,
-  WidgetFrameDisclosurePanel,
-  WidgetFrameDisclosureTrigger,
-  WidgetLoadingState,
-  WidgetSubtitle,
-} from "@you-agent-factory/components/recipes";
-
-export function ExamplePanel({
-  loading,
-  title,
-}: {
-  loading: boolean;
-  title: string;
-}) {
-  const [expanded, setExpanded] = useState(false);
-  const panelID = "example-panel-details";
-
-  return (
-    <WidgetFrame
-      headerAction={
-        <button type="button" onClick={() => undefined}>
-          Refresh
-        </button>
-      }
-      title={title}
-    >
-      <WidgetSubtitle>42 host-provided items</WidgetSubtitle>
-      {loading ? (
-        <WidgetLoadingState>
-          <WidgetEmptyStateTitle>Loading content</WidgetEmptyStateTitle>
-          <WidgetEmptyStateText>Host-provided loading message.</WidgetEmptyStateText>
-        </WidgetLoadingState>
-      ) : (
-        <WidgetDetailCopy>Host-provided detail copy.</WidgetDetailCopy>
-      )}
-      <WidgetFrameDisclosure>
-        <WidgetFrameDisclosureTrigger
-          controlsID={panelID}
-          expanded={expanded}
-          onExpandedChange={setExpanded}
-        >
-          {expanded ? "Collapse details" : "Expand details"}
-        </WidgetFrameDisclosureTrigger>
-        <WidgetFrameDisclosurePanel expanded={expanded} id={panelID}>
-          <WidgetDetailCopy>Host-provided disclosure content.</WidgetDetailCopy>
-        </WidgetFrameDisclosurePanel>
-      </WidgetFrameDisclosure>
-    </WidgetFrame>
-  );
-}
-```
-
-## Key props and layout helpers
-
-### `WidgetFrame`
-
-| Prop | Purpose |
-| --- | --- |
-| `title` | Required accessible name (`aria-label` on the frame article). |
-| `children` | Host content region inside the body grid. |
-| `headerAction` | Optional header tools slot (buttons, menus). A spacer preserves header height when omitted. |
-| `wide` | Applies minimum body height for wide dashboard columns. |
-| `bodyScroll` | Enables scrollable body (`overflow-auto`). Defaults to `true`. |
-| `className` / `bodyClassName` | Host layout overrides. Apply `widgetFrameDetailCardClass` via `className` when rendering description lists. |
-
-Layout constants exported for host composition:
-
-- `widgetFrameDetailCardClass` — description-list spacing inside framed detail cards.
-- `WIDGET_FRAME_MIN_WIDTH_CLASS` — `min-w-0` shrink guard for grid parents.
-- `WIDGET_FRAME_WIDE_BODY_CLASS` — minimum body height for wide layouts.
-- `WIDGET_FRAME_RESPONSIVE_SHELL_CLASS` — full-width responsive shell helper.
-
-### State shells
-
-| Component | Semantics | Host provides |
-| --- | --- | --- |
-| `WidgetLoadingState` | `role="status"`, `aria-busy="true"` | Loading copy via children; optional `placeholder` or `showDefaultPlaceholder={false}`. |
-| `WidgetErrorState` | `role="alert"` | Error title and message via children. |
-| `WidgetSuccessState` | `role="status"` | Success title and message via children. |
-| `WidgetEmptyState` | Neutral dashed panel | Empty title/text via `WidgetEmptyStateTitle` / `WidgetEmptyStateText` or arbitrary children. |
-
-State shells never invent domain-specific text. All user-visible strings come from
-the host.
-
-### Disclosure (collapsed / expanded)
-
-Use controlled state from the host:
-
-- `WidgetFrameDisclosureTrigger` requires `controlsID`, `expanded`, and optional `onExpandedChange`.
-- `WidgetFrameDisclosurePanel` requires matching `id` and `expanded`.
-- Triggers expose `aria-expanded`, `aria-controls`, keyboard focus rings, and `type="button"`.
-- Panels use the `hidden` attribute when collapsed.
-
-Icon-only triggers must pass `aria-label`. Labeled triggers use visible button text.
-
-### Responsive layout helpers
-
-For Storybook demos and host layout tests:
-
-- `widgetFrameStoryShellStyle(maxWidth)` — bounded shell wrapper style object.
-- `widgetFrameHasNoHorizontalOverflow(element)` — pure helper for overflow checks.
-- `WIDGET_FRAME_STORY_SHELL_DATA_ATTR` — `data-widget-frame-story-shell` marker for test shells.
-
-## Accessibility expectations
-
-- Frame title renders as a level-3 heading inside a landmark `article` labeled with the same title text.
-- Loading, error, and success regions use appropriate live-region roles; do not nest conflicting roles.
-- Disclosure triggers are keyboard operable buttons with visible `focus-visible` outlines.
-- Header actions supplied by the host must include accessible names (`aria-label` or visible text).
-- Host copy inside alerts and status regions should use heading + body structure for screen-reader scanability.
-
-## Storybook visual reference
-
-Package Storybook lives under `Recipes/WidgetFrame`. Stories use package imports
-and package token decorators only — no dashboard providers.
-
-| Story | Storybook id | Demonstrates |
-| --- | --- | --- |
-| Success content | `recipes-widgetframe--success-content` | Default framed content |
-| Empty state | `recipes-widgetframe--empty-state` | Host-provided empty copy |
-| Loading state | `recipes-widgetframe--loading-state` | `WidgetLoadingState` + placeholder |
-| Error state | `recipes-widgetframe--error-state` | `WidgetErrorState` alert treatment |
-| Success state | `recipes-widgetframe--success-state` | `WidgetSuccessState` treatment |
-| Collapsed disclosure | `recipes-widgetframe--collapsed-disclosure` | Controlled collapse + expand interaction |
-| Expanded disclosure | `recipes-widgetframe--expanded-disclosure` | Expanded panel visibility |
-| Responsive compact | `recipes-widgetframe--responsive-compact` | 360px bounded shell |
-| Responsive medium | `recipes-widgetframe--responsive-medium` | 768px bounded shell |
-| Responsive wide | `recipes-widgetframe--responsive-wide` | 1280px bounded shell |
-
-Run package Storybook locally:
-
-```bash
-cd ui/packages/components
-bun run storybook
-```
-
-Browser verification for documented stories:
-
-```bash
-cd ui/packages/components
-bun run verify:widget-frame-docs
-```
-
-Responsive overflow checks (compact + wide at mobile and desktop viewports):
-
-```bash
-cd ui/packages/components
-bun run verify:widget-frame-responsive
-```
-
-## Allowed dependencies
-
-Recipe source may import:
-
-- Package utilities (`cn` from `@you-agent-factory/components/utilities`)
-- Package token CSS via the host `styles.css` import
-- React and `react-dom` peer dependencies
-
-Recipe source must **not** import:
-
-- Dashboard feature modules, routes, or bento grid (`react-grid-layout`)
-- Generated OpenAPI clients or dashboard API adapters
-- React Query, Zustand, Monaco, Sonner, or dashboard i18n/session providers
-- Factory/work/session/provider domain types
-
-`check:package-boundary` enforces these rules in CI.
-
-## Source-copy guidance
-
-Teams may copy recipe files into a host repository to customize markup while
-keeping the same token foundation:
-
-1. Import `@you-agent-factory/components/styles.css` in the host app.
-2. Copy only the recipe files you need from `src/recipes/`.
-3. Keep copied code on the package side of your boundary — do not pull dashboard
-   modules into copied recipe files.
-4. Retain host ownership of copy, data fetching, disclosure state, and action handlers.
-
-**No source-copy CLI or generator ships with this package.** Copy-and-adapt
-workflows are manual and maintained by the host application.
-
-## Dashboard integration note
-
-The dashboard keeps bento composition (`AgentBentoCard`, grid layout, widget
-picker) in feature code. Dashboard widgets import recipe content primitives from
-`@you-agent-factory/components/recipes` while `DashboardWidgetFrame` remains a
-dashboard-owned wrapper that applies bento-specific chrome.
-
-When adopting recipes outside the dashboard, compose `WidgetFrame` directly and
-supply your own header actions, state, and slot content.

package/src/category-paths.ts

@@ -1,20 +0,0 @@
-/** Planned deep import paths for `@you-agent-factory/components` category entrypoints. */
-export const COMPONENT_CATEGORY_EXPORT_PATHS = [
-  "primitives",
-  "forms",
-  "layout",
-  "feedback",
-  "data-display",
-  "navigation",
-  "overlays",
-  "charts",
-  "graphs",
-  "recipes",
-  "icons",
-  "utilities",
-  "testing",
-  "tokens",
-] as const;
-
-export type ComponentCategoryExportPath =
-  (typeof COMPONENT_CATEGORY_EXPORT_PATHS)[number];

package/src/charts/chart-state-panel.tsx

@@ -1,103 +0,0 @@
-import type { HTMLAttributes, ReactNode } from "react";
-
-import { cn } from "../utilities/cn";
-
-import type { ChartPresentation } from "./chart";
-
-export type ChartStateStatus = "empty" | "error" | "loading" | "success";
-
-export interface ChartStatePanelProps extends HTMLAttributes<HTMLDivElement> {
-  action?: ReactNode;
-  description: string;
-  presentation?: ChartPresentation;
-  status: ChartStateStatus;
-  title: string;
-}
-
-// tailwind-exception: intrinsic-sizing
-const CHART_STATE_PANEL_CLASS =
-  "flex h-full min-h-[14rem] min-w-0 w-full flex-1 flex-col justify-center";
-// tailwind-exception: intrinsic-sizing
-const CHART_STATE_PANEL_EMBEDDED_CLASS =
-  "grid min-h-[14rem] min-w-0 w-full flex-1 flex-col items-start justify-center gap-1.5 p-0 [&_h3]:m-0";
-const CHART_STATE_PANEL_STANDALONE_SHELL_CLASS =
-  "grid min-h-60 items-start gap-1.5 rounded-2xl border border-dashed border-outline-variant bg-surface-container-low p-5 [&_h3]:m-0";
-const CHART_STATE_PANEL_TITLE_CLASS =
-  "m-0 text-title-medium font-semibold text-on-surface";
-const CHART_STATE_PANEL_DESCRIPTION_CLASS = "m-0 text-body-medium text-on-surface-variant";
-const CHART_STATE_PANEL_SKELETON_CLASS = "animate-pulse rounded-xl bg-af-overlay";
-
-function chartStateRole(status: ChartStateStatus): "alert" | "status" {
-  return status === "error" ? "alert" : "status";
-}
-
-function chartStateLive(status: ChartStateStatus): "assertive" | "polite" {
-  return status === "error" ? "assertive" : "polite";
-}
-
-export function ChartStatePanel({
-  action,
-  className,
-  description,
-  presentation = "standalone",
-  status,
-  title,
-  ...props
-}: ChartStatePanelProps) {
-  const embedded = presentation === "embedded";
-  const role = chartStateRole(status);
-  const ariaLive = chartStateLive(status);
-  const loading = status === "loading";
-
-  const content = (
-    <>
-      {loading ? (
-        <div aria-hidden="true" className="grid w-full gap-3">
-          <div className={cn(CHART_STATE_PANEL_SKELETON_CLASS, "h-4 w-32")} />
-          <div className={cn(CHART_STATE_PANEL_SKELETON_CLASS, "h-28 w-full")} />
-        </div>
-      ) : null}
-      <h3 className={CHART_STATE_PANEL_TITLE_CLASS}>{title}</h3>
-      <p className={CHART_STATE_PANEL_DESCRIPTION_CLASS}>{description}</p>
-      {action ? <div className="mt-2">{action}</div> : null}
-    </>
-  );
-
-  if (!embedded) {
-    return (
-      <div
-        aria-busy={loading || undefined}
-        aria-live={ariaLive}
-        className={cn(
-          CHART_STATE_PANEL_STANDALONE_SHELL_CLASS,
-          CHART_STATE_PANEL_CLASS,
-          className,
-        )}
-        data-chart-presentation={presentation}
-        data-chart-state={status}
-        role={role}
-        {...props}
-      >
-        {content}
-      </div>
-    );
-  }
-
-  return (
-    <div
-      aria-busy={loading || undefined}
-      aria-live={ariaLive}
-      className={cn(
-        CHART_STATE_PANEL_EMBEDDED_CLASS,
-        CHART_STATE_PANEL_CLASS,
-        className,
-      )}
-      data-chart-presentation={presentation}
-      data-chart-state={status}
-      role={role}
-      {...props}
-    >
-      {content}
-    </div>
-  );
-}

package/src/charts/chart.tsx

@@ -1,287 +0,0 @@
-import type {
-  CSSProperties,
-  HTMLAttributes,
-  MouseEvent as ReactMouseEvent,
-  ReactNode,
-} from "react";
-import { createContext, useContext } from "react";
-import {
-  Legend as RechartsLegend,
-  Tooltip as RechartsTooltip,
-  ResponsiveContainer,
-  type TooltipContentProps,
-} from "recharts";
-import type {
-  LegendPayload,
-  Props as RechartsLegendContentProps,
-} from "recharts/types/component/DefaultLegendContent";
-import type {
-  NameType,
-  ValueType,
-} from "recharts/types/component/DefaultTooltipContent";
-
-import { cn } from "../utilities/cn";
-
-export interface ChartConfigEntry {
-  color: string;
-  label: string;
-}
-
-export type ChartConfig = Record<string, ChartConfigEntry>;
-
-const ChartContext = createContext<ChartConfig | null>(null);
-
-export type ChartPresentation = "embedded" | "standalone";
-
-// tailwind-exception: intrinsic-sizing
-const CHART_CONTAINER_STANDALONE_CLASS =
-  "relative h-[18rem] rounded-2xl border border-outline bg-surface-container-low p-4 text-on-surface";
-// tailwind-exception: intrinsic-sizing
-const CHART_CONTAINER_EMBEDDED_CLASS =
-  "relative flex h-full min-h-0 min-w-0 w-full flex-1 flex-col text-on-surface";
-const DEFAULT_CHART_INITIAL_DIMENSION = { height: 288, width: 640 } as const;
-
-const CHART_LEGEND_BUTTON_CLASS =
-  "inline-flex min-h-0 items-center justify-center rounded-md border border-transparent bg-transparent px-0 py-1 text-left text-xs font-normal text-on-surface-variant focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-af-focus";
-
-function chartContainerClassName(
-  presentation: ChartPresentation,
-  className?: string,
-): string {
-  return cn(
-    presentation === "embedded"
-      ? CHART_CONTAINER_EMBEDDED_CLASS
-      : CHART_CONTAINER_STANDALONE_CLASS,
-    className,
-  );
-}
-
-function useChartConfig() {
-  const context = useContext(ChartContext);
-
-  if (context === null) {
-    throw new Error("Chart components must be rendered inside ChartContainer.");
-  }
-
-  return context;
-}
-
-export function ChartContainer({
-  children,
-  className,
-  config,
-  footer,
-  interactionAttributes,
-  overlay,
-  presentation = "standalone",
-  rootAttributes,
-  style,
-  title,
-}: {
-  children: ReactNode;
-  className?: string;
-  config: ChartConfig;
-  footer?: ReactNode;
-  interactionAttributes?: HTMLAttributes<HTMLDivElement>;
-  overlay?: ReactNode;
-  presentation?: ChartPresentation;
-  rootAttributes?: Record<string, string>;
-  style?: CSSProperties;
-  title: string;
-}) {
-  const chartSurface = (
-    <ResponsiveContainer
-      height="100%"
-      initialDimension={DEFAULT_CHART_INITIAL_DIMENSION}
-      minHeight={0}
-      minWidth={0}
-      width="100%"
-    >
-      {children}
-    </ResponsiveContainer>
-  );
-
-  return (
-    <ChartContext.Provider value={config}>
-      <div
-        aria-label={title}
-        className={chartContainerClassName(presentation, className)}
-        data-chart-container=""
-        data-chart-presentation={presentation}
-        role="img"
-        {...interactionAttributes}
-        {...rootAttributes}
-        style={
-          {
-            ...Object.fromEntries(
-              Object.entries(config).map(([key, value]) => [
-                `--color-${key}`,
-                value.color,
-              ]),
-            ),
-            ...style,
-          } as CSSProperties
-        }
-      >
-        {overlay ? (
-          <div className="pointer-events-none absolute inset-0">{overlay}</div>
-        ) : null}
-        {footer ? (
-          <div className="flex min-h-0 flex-1 basis-0 flex-col">
-            <div className="h-full min-h-0 flex-1 basis-0">{chartSurface}</div>
-            {footer}
-          </div>
-        ) : (
-          chartSurface
-        )}
-      </div>
-    </ChartContext.Provider>
-  );
-}
-
-export const ChartTooltip = RechartsTooltip;
-export const ChartLegend = RechartsLegend;
-
-export function ChartTooltipContent({
-  active,
-  className,
-  label,
-  payload,
-}: TooltipContentProps<ValueType, NameType> & { className?: string }) {
-  const config = useChartConfig();
-
-  if (!active || !payload?.length) {
-    return null;
-  }
-
-  return (
-    <div
-      className={cn(
-        "grid min-w-40 gap-2 rounded-xl border border-outline bg-surface-container-high px-3 py-2 text-sm shadow-af-card",
-        className,
-      )}
-    >
-      <p className="m-0 font-semibold text-on-surface">{String(label)}</p>
-      <div className="grid gap-1">
-        {payload.map((entry) => {
-          const key = entry.dataKey?.toString() ?? "";
-          const item = config[key];
-
-          return (
-            <div
-              className="flex items-center justify-between gap-3 text-on-surface-variant"
-              key={key}
-            >
-              <div className="flex items-center gap-2">
-                <span
-                  className="h-2.5 w-2.5 rounded-full"
-                  style={{
-                    backgroundColor:
-                      item?.color ?? entry.color ?? "currentColor",
-                  }}
-                />
-                <span>{item?.label ?? key}</span>
-              </div>
-              <span className="font-medium text-on-surface">{entry.value}</span>
-            </div>
-          );
-        })}
-      </div>
-    </div>
-  );
-}
-
-export function ChartLegendContent({
-  className,
-  getToggleLabel,
-  hiddenSeries = new Set<string>(),
-  itemClassName,
-  onToggleSeries,
-  payload,
-  swatchClassName,
-}: RechartsLegendContentProps & {
-  className?: string;
-  getToggleLabel?: (label: string, hidden: boolean) => string;
-  hiddenSeries?: ReadonlySet<string>;
-  itemClassName?: string;
-  onToggleSeries?: (key: string) => void;
-  swatchClassName?: string;
-}) {
-  const config = useChartConfig();
-
-  if (!payload?.length) {
-    return null;
-  }
-
-  const stopChartInteraction = (event: ReactMouseEvent<HTMLButtonElement>) => {
-    event.stopPropagation();
-  };
-
-  return (
-    <div
-      className={cn(
-        "flex flex-wrap items-center gap-4 pt-3 text-xs text-on-surface-variant",
-        className,
-      )}
-    >
-      {payload.map((entry: LegendPayload) => {
-        const key = entry.dataKey?.toString() ?? "";
-        const item = config[key];
-        const label = item?.label ?? key;
-        const hidden = hiddenSeries.has(key);
-        const content = (
-          <>
-            <span
-              aria-hidden="true"
-              className={cn(
-                "rounded-full",
-                swatchClassName ?? "h-2.5 w-2.5",
-                hidden ? "border border-outline bg-surface-container-low" : "",
-              )}
-              style={{
-                backgroundColor: hidden
-                  ? undefined
-                  : (item?.color ?? entry.color ?? "currentColor"),
-              }}
-            />
-            <span>{label}</span>
-          </>
-        );
-
-        if (!onToggleSeries) {
-          return (
-            <div
-              className={cn("flex items-center gap-2", itemClassName)}
-              key={key}
-            >
-              {content}
-            </div>
-          );
-        }
-
-        return (
-          <button
-            aria-label={getToggleLabel?.(label, hidden) ?? label}
-            aria-pressed={!hidden}
-            className={cn(
-              CHART_LEGEND_BUTTON_CLASS,
-              hidden ? "text-on-surface-disabled" : "",
-              itemClassName,
-            )}
-            data-chart-legend-series={key}
-            data-chart-legend-series-hidden={hidden ? "true" : "false"}
-            key={key}
-            onClick={(event) => {
-              event.stopPropagation();
-              onToggleSeries(key);
-            }}
-            onMouseDown={stopChartInteraction}
-            type="button"
-          >
-            {content}
-          </button>
-        );
-      })}
-    </div>
-  );
-}

package/src/charts/index.ts

@@ -1,21 +0,0 @@
-/** Stable category path for `@you-agent-factory/components/charts`. */
-export const COMPONENTS_CATEGORY = "charts" as const;
-
-export type ComponentsCategory = typeof COMPONENTS_CATEGORY;
-
-export {
-  ChartContainer,
-  ChartLegend,
-  ChartLegendContent,
-  ChartTooltip,
-  ChartTooltipContent,
-  type ChartConfig,
-  type ChartConfigEntry,
-  type ChartPresentation,
-} from "./chart";
-
-export {
-  ChartStatePanel,
-  type ChartStatePanelProps,
-  type ChartStateStatus,
-} from "./chart-state-panel";