npm - @you-agent-factory/components - Versions diffs - 0.0.0 - Mend

@you-agent-factory/components 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (92) hide show

package/README.md +223 -0
package/docs/README.md +83 -0
package/docs/button.md +119 -0
package/docs/charts.md +325 -0
package/docs/data-display-code-panel.md +120 -0
package/docs/feedback-alert-panel.md +117 -0
package/docs/feedback-skeleton.md +54 -0
package/docs/forms-form-field.md +490 -0
package/docs/forms-input-primitives.md +311 -0
package/docs/forms-select-primitives.md +362 -0
package/docs/graphs.md +250 -0
package/docs/layout-display-primitives.md +211 -0
package/docs/overlays.md +414 -0
package/docs/table-data-table.md +331 -0
package/docs/typography-roles.md +182 -0
package/docs/widget-frame-recipes.md +273 -0
package/package.json +161 -0
package/src/category-paths.ts +20 -0
package/src/charts/chart-state-panel.tsx +103 -0
package/src/charts/chart.tsx +287 -0
package/src/charts/index.ts +21 -0
package/src/data-display/code-panel.tsx +67 -0
package/src/data-display/data-table.tsx +180 -0
package/src/data-display/description-list.tsx +24 -0
package/src/data-display/index.ts +34 -0
package/src/data-display/table-layout.ts +12 -0
package/src/data-display/table.tsx +131 -0
package/src/feedback/alert-panel-semantics.ts +75 -0
package/src/feedback/alert-panel.tsx +187 -0
package/src/feedback/index.ts +21 -0
package/src/feedback/skeleton.tsx +16 -0
package/src/forms/index.ts +73 -0
package/src/forms/package-checkbox.tsx +50 -0
package/src/forms/package-enum-select.tsx +185 -0
package/src/forms/package-file-input.tsx +25 -0
package/src/forms/package-form-field.tsx +202 -0
package/src/forms/package-input.tsx +25 -0
package/src/forms/package-native-select.tsx +25 -0
package/src/forms/package-select.tsx +209 -0
package/src/forms/package-textarea.tsx +35 -0
package/src/forms/select-icons.tsx +35 -0
package/src/graphs/graph-edge-path.ts +241 -0
package/src/graphs/graph-edge.tsx +130 -0
package/src/graphs/graph-interactive-example.tsx +187 -0
package/src/graphs/graph-node-button.tsx +51 -0
package/src/graphs/graph-node-handle-badge.tsx +108 -0
package/src/graphs/graph-node-handle.ts +28 -0
package/src/graphs/graph-node-shell.tsx +111 -0
package/src/graphs/graph-node-state-indicator.tsx +47 -0
package/src/graphs/graph-node-state.ts +111 -0
package/src/graphs/graph-viewport-surface.tsx +27 -0
package/src/graphs/index.ts +41 -0
package/src/icons/index.ts +4 -0
package/src/index.ts +209 -0
package/src/layout/action-row.tsx +53 -0
package/src/layout/index.ts +9 -0
package/src/layout/surface-panel.tsx +91 -0
package/src/navigation/index.ts +4 -0
package/src/overlays/collapsible.tsx +22 -0
package/src/overlays/dialog.tsx +148 -0
package/src/overlays/index.ts +31 -0
package/src/overlays/overlay-layout.ts +9 -0
package/src/overlays/popover.tsx +29 -0
package/src/overlays/scroll-area.tsx +78 -0
package/src/primitives/button-link.tsx +22 -0
package/src/primitives/button.tsx +258 -0
package/src/primitives/icon-button-shell.tsx +49 -0
package/src/primitives/index.ts +31 -0
package/src/primitives/package-text.tsx +29 -0
package/src/primitives/typography-roles.ts +12 -0
package/src/primitives/typography.tsx +165 -0
package/src/recipes/index.ts +61 -0
package/src/recipes/widget-frame-content.tsx +114 -0
package/src/recipes/widget-frame-disclosure.tsx +161 -0
package/src/recipes/widget-frame-layout.ts +40 -0
package/src/recipes/widget-frame-skeleton.tsx +16 -0
package/src/recipes/widget-frame-states.tsx +99 -0
package/src/recipes/widget-frame-typography.ts +19 -0
package/src/recipes/widget-frame.tsx +84 -0
package/src/styles/color-palette-presets.css +167 -0
package/src/styles/color-role-tokens.css +163 -0
package/src/styles/layout-role-tokens.css +27 -0
package/src/styles/text-color-role-tokens.css +29 -0
package/src/styles/typography-role-tokens.css +72 -0
package/src/styles/typography-role-utilities.css +73 -0
package/src/styles/typography-roles.css +53 -0
package/src/styles.css +32 -0
package/src/testing/index.ts +13 -0
package/src/testing/render.tsx +16 -0
package/src/tokens/index.ts +4 -0
package/src/utilities/cn.ts +5 -0
package/src/utilities/index.ts +6 -0

package/README.md ADDED Viewed

@@ -0,0 +1,223 @@
+# @you-agent-factory/components
+Presentation components, shared design tokens, and small utilities for building
+factory-style UIs outside the dashboard. The package is domain-free: it does not
+ship data fetching, durable state, business workflows, or product copy.
+## Install and workspace setup
+Add the package to your application dependencies. In this monorepo the dashboard
+uses a workspace link:
+```json
+{
+  "dependencies": {
+    "@you-agent-factory/components": "file:./packages/components"
+  }
+}
+```
+Published consumers should depend on the same package name
+(`@you-agent-factory/components`) from their chosen distribution channel.
+Peer dependencies:
+- `react` ^19.0.0
+- `react-dom` ^19.0.0
+Some category entrypoints (for example charts and graphs) also require the
+package's direct dependencies (`recharts`, `@xyflow/react`). Install those in
+the host app when you import those categories.
+## Import package styles
+Import the package styles entrypoint once in your application CSS (or an
+equivalent global stylesheet hook) before rendering components:
+```css
+@import "@you-agent-factory/components/styles.css";
+```
+With Tailwind CSS v4, a typical host `styles.css` also imports Tailwind and may
+layer app-specific utilities after the package tokens:
+```css
+@import "tailwindcss";
+@import "@you-agent-factory/components/styles.css";
+/* Host-only utilities and foundation overrides */
+```
+The entrypoint exposes shared role tokens, palette presets, typography tokens,
+and layout tokens. Host applications do not need dashboard routes, providers,
+API clients, or generated OpenAPI types to use these tokens.
+## Import components and utilities
+Category entrypoints are deep imports under the package name:
+```ts
+import { COMPONENTS_PACKAGE_NAME } from "@you-agent-factory/components";
+import * as primitives from "@you-agent-factory/components/primitives";
+import * as forms from "@you-agent-factory/components/forms";
+import { cn } from "@you-agent-factory/components/utilities";
+```
+`COMPONENTS_PACKAGE_NAME` is the stable package identifier
+(`"@you-agent-factory/components"`). Category paths include `primitives`, `forms`,
+`layout`, `feedback`, `data-display`, `navigation`, `overlays`, `charts`,
+`graphs`, `recipes`, `icons`, `utilities`, `testing`, and `tokens`.
+Use `cn` from `@you-agent-factory/components/utilities` for class name composition
+in component code instead of dashboard-local helpers.
+## Consumer responsibilities
+The component package owns presentation: markup, styles, tokens, and generic
+utilities. Host applications own everything domain-specific:
+- **Data fetching** — API calls, caching, and synchronization with backend
+  services.
+- **Durable state** — session persistence, undo/redo, and cross-route state
+  that outlives a single render.
+- **Business workflows** — factory orchestration, validation rules, and product
+  behavior tied to your domain model.
+- **Domain copy** — user-visible strings, labels, and messaging for your
+  product.
+Pass data and callbacks into components as props; do not expect the package to
+reach into your app's stores, routers, or API layer.
+## Theming
+Theme through package tokens and semantic roles, not dashboard-specific CSS.
+1. **Palette presets** — Set `data-color-palette` on a root element (or
+   `:root`) to select a built-in preset. Available presets include
+   `factory-dark`, `factory-light`, `material-baseline`, `slate`, and `olive`.
+   Presets override `--color-af-foundation-*` keys defined in the package token
+   layer.
+   ```html
+   <html data-color-palette="factory-dark">
+   ```
+2. **Semantic role tokens** — Components consume roles such as
+   `--color-background`, `--color-surface`, `--color-primary`, and typography
+   roles from the package token CSS. Prefer these roles in custom styles
+   instead of hard-coded hex values or dashboard-only class names.
+3. **Host foundation keys** — When you need a custom brand baseline, override
+   `--color-af-foundation-*` variables in your host stylesheet after importing
+   package styles. Role tokens and palette presets cascade from those keys.
+The package does not require the dashboard `styles.css` or dashboard-only
+utility sheets.
+## Source-copy guidance (documentation only)
+Some teams copy component source into their repository to customize markup or
+styles while keeping the same token foundation. Supported patterns today:
+1. Import `@you-agent-factory/components/styles.css` in the host app so copied
+   components receive the same tokens.
+2. Copy the component files you need from the package category you depend on.
+3. Keep copied code on the package side of your boundary — do not pull in
+   dashboard modules, API clients, or generated OpenAPI types.
+**This README describes source-copy as guidance only.** No source-copy CLI,
+install command, or code generator is shipped as part of this package. Any
+copy-and-adapt workflow is manual and maintained by the host application.
+## Per-component documentation
+Per-component usage notes, props tables, and examples live in the package docs
+directory:
+- [`docs/`](./docs/)
+- [Button primitives](./docs/button.md) — semantic variants, `ButtonLink`
+  guidance, loading behavior, and icon-only accessibility labels.
+- [Typography roles](./docs/typography-roles.md) — `Text`, `Heading`, `Label`,
+  `Code`, dense text, truncation, and wrapping
+- [Layout and display primitives](./docs/layout-display-primitives.md) —
+  `SurfacePanel`, `ActionRow`, `DescriptionList`, and responsive layout guidance
+- [`docs/graphs.md`](./docs/graphs.md) — graph node shell, node button, edge,
+  viewport surface, handle badge, edge path helpers, React Flow boundary, and
+  Storybook example map
+- [AlertPanel semantic feedback variants](./docs/feedback-alert-panel.md)
+- [Skeleton loading placeholders](./docs/feedback-skeleton.md)
+- [CodePanel long-content containment](./docs/data-display-code-panel.md)
+- [Table primitives and DataTable](./docs/table-data-table.md)
+- [Form input primitives](./docs/forms-input-primitives.md)
+- [Form field structure and messaging](./docs/forms-form-field.md) — `FormField`,
+  labels, descriptions, helper text, warnings, errors, success messages,
+  grouped-control semantics, and host validation responsibilities
+- [Form select primitives](./docs/forms-select-primitives.md) — `Select`,
+  `NativeSelect`, `EnumSelect`, keyboard behavior, and option contracts
+- [Overlay and disclosure primitives](./docs/overlays.md)
+- [Widget frame and layout recipes](./docs/widget-frame-recipes.md)
+See that directory for component-level documentation as it is added. The docs
+shell is plain markdown in version control; it does not require a docs-site
+route, generated registry, or additional build-time documentation tooling.
+- [Charts](./docs/charts.md) — config, presentation, tooltip and legend,
+  state panels, and caller-owned series state
+## Development
+From `ui/packages/components`:
+```bash
+bun run typecheck
+bun run test
+bun run check:package-boundary
+bun run check:package-dependency-direction
+bun run build-storybook
+bun run verify:storybook-browser
+```
+Package tests use `src/testing/vitest.setup.ts` and `src/testing/render.tsx`
+for DOM cleanup, accessible assertions, and user interactions. They do not
+require dashboard routes, providers, generated clients, API mocks, React
+Query, Zustand, Monaco, or Sonner.
+Package Storybook lives in `.storybook/` and discovers `src/**/*.stories.tsx`
+files. Preview decorators import the package token fixture stylesheet and
+apply `data-color-palette` locally; they do not mount dashboard session,
+i18n, API, React Query, Zustand, Monaco, or Sonner providers.
+`check:package-boundary` scans package production source and fails when files
+import dashboard API modules, feature modules, generated OpenAPI clients,
+dashboard i18n providers, dashboard session providers, React Query, Zustand,
+Monaco, or Sonner. Violations report the package file and import path.
+`check:package-dependency-direction` scans package production source and fails
+when a lower package layer imports a higher layer (for example primitives
+importing recipes) or when production source imports testing support modules.
+Violations report the package file, import path, and both source and target
+layers.
+From the repository root:
+```bash
+make ui-components-typecheck
+make ui-components-test
+make ui-components-storybook
+make ui-components-boundary
+make ui-components-dependency-direction
+make ui-components-verify
+make ui-lint
+```
+`make ui-components-verify` runs the full component package harness with labeled
+failure output for typecheck, tests, Storybook build, boundary checks, and
+dependency-direction checks. CI runs the same harness in the Build, Lint, and API
+workflow after dashboard lint.
+From the `ui` workspace root:
+```bash
+make ui-lint
+bun run check:semantic-colors
+```

package/docs/README.md ADDED Viewed

@@ -0,0 +1,83 @@
+# Component package documentation
+Per-component usage notes, props tables, and examples belong in this
+directory. Add one markdown file per component (or small component group) as
+those surfaces are documented.
+## What belongs here
+- Import paths and category entrypoints for a component
+- Props, variants, and accessibility notes
+- Short usage examples that do not depend on dashboard routes or API clients
+## What does not belong here
+- Dashboard-only wiring, data fetching, or business workflow guides
+- Generated docs registries, docs-site routes, or build-time documentation
+  tooling
+This docs shell is plain markdown kept under version control. Host applications
+read it directly from the package; no docs-site implementation is required.
+## Documented components
+- [Button primitives](./button.md) — `Button`, `ButtonLink`, `IconButtonShell`,
+  semantic variants, loading behavior, and icon-only accessibility labels.
+- [Typography roles](./typography-roles.md) — `Text`, `Heading`, `Label`,
+  `Code`, dense text, truncation, and wrapping
+- [Layout and display primitives](./layout-display-primitives.md) —
+  `SurfacePanel`, `ActionRow`, `DescriptionList`, and responsive layout guidance
+- [Form select primitives](./forms-select-primitives.md) — `Select`,
+  `NativeSelect`, `EnumSelect`, keyboard behavior, and option contracts
+- [Form field structure and messaging](./forms-form-field.md) — `FormField`,
+  labels, descriptions, helper text, warnings, errors, success messages,
+  grouped-control semantics, and host validation responsibilities
+- [Overlay and disclosure primitives](./overlays.md) — Dialog, Popover,
+  Collapsible, and ScrollArea accessibility, labeling, focus, and overflow
+  guidance.
+## Getting started
+See the package [README](../README.md) for install, CSS import setup, theming,
+and consumer dependency boundaries. Link new component docs from that README or
+from sibling files in this directory as the library grows.
+## Component guides
+- [Charts](./charts.md) — `ChartContainer`, tooltip and legend content, state
+  panels, config types, and host-owned data boundaries
+## Form input primitives
+- [Form input primitives](./forms-input-primitives.md) — import paths, controlled
+  versus uncontrolled usage, host accessibility responsibilities, and
+  presentation-only boundaries for text input, textarea, checkbox, and file input.
+- [Form field structure and messaging](./forms-form-field.md) — `FormField`,
+  labels, descriptions, helper text, warnings, errors, success messages,
+  grouped-control semantics, `buildFormFieldAriaDescribedBy`, and host validation
+  responsibilities.
+## Feedback and code display
+- [AlertPanel](./feedback-alert-panel.md) — semantic feedback variants, token
+  mapping, accessibility, and Storybook references
+- [Skeleton](./feedback-skeleton.md) — loading placeholders, busy regions, and
+  empty vs loading feedback
+- [CodePanel](./data-display-code-panel.md) — long-line and long-block
+  containment, scrolling, and responsive layout expectations
+## Table data display
+- [Table primitives and DataTable](./table-data-table.md) — generic row contract,
+  explicit data states, density and responsive layout helpers, accessibility,
+  and Storybook references for domain-free tabular data display.
+## Widget layout recipes
+- [Graph primitives](./graphs.md) — `@you-agent-factory/components/graphs`
+  contracts, React Flow boundary, host responsibilities, and Storybook example
+  map
+- [Widget frame and layout recipes](./widget-frame-recipes.md) — import paths,
+  state ownership, accessibility, Storybook references, and source-copy guidance
+  for domain-free framed panels.

package/docs/button.md ADDED Viewed

@@ -0,0 +1,119 @@
+# Button primitives
+`Button`, `ButtonLink`, and `IconButtonShell` are the reusable action primitives in
+`@you-agent-factory/components`. They provide semantic tones, loading behavior,
+icon-only sizing, and shared focus-visible treatment without dashboard routes,
+providers, API clients, or generated OpenAPI types.
+## Import paths
+```ts
+import {
+  Button,
+  ButtonLink,
+  IconButtonShell,
+  buttonVariants,
+  type ButtonProps,
+  type ButtonLinkProps,
+  type IconButtonShellProps,
+} from "@you-agent-factory/components";
+import {
+  Button as PrimitiveButton,
+  ButtonLink as PrimitiveButtonLink,
+  IconButtonShell as PrimitiveIconButtonShell,
+} from "@you-agent-factory/components/primitives";
+```
+Import `@you-agent-factory/components/styles.css` once in the host application
+before rendering buttons. See the package [README](../README.md) for CSS setup.
+## Button vs ButtonLink
+| Primitive | Renders | Use when |
+| --- | --- | --- |
+| `Button` | `<button>` (or child via `asChild`) | The action stays on the current view: submit forms, open dialogs, trigger async work, or run in-place commands. |
+| `ButtonLink` | `<a>` styled with shared button tokens | Navigation should use a real link: route changes, external URLs, or downloads where anchor semantics and `href` behavior are required. |
+`ButtonLink` does not support `loading` because anchor elements do not expose the
+same busy/disabled interaction model as buttons. Show progress elsewhere when a
+navigation target is not yet ready.
+`Button` supports `asChild` for composition, but prefer `ButtonLink` when the
+rendered element must be an anchor.
+## Semantic button variants
+Set `tone` on `Button` and `ButtonLink`, or on `IconButtonShell` for toolbar
+actions. Variants map to semantic roles rather than dashboard feature styling.
+| `tone` | Role | When to use |
+| --- | --- | --- |
+| `default` | Primary | The single most important action in a section or dialog footer. |
+| `secondary` | Secondary | Supporting actions that still need button emphasis, such as "Save draft". |
+| `outline` | Outline | Neutral actions on busy surfaces or paired secondary controls in toolbars. |
+| `ghost` | Ghost | Low-emphasis actions on dense panels where borders would add noise. |
+| `destructive` | Destructive | Irreversible or high-risk operations such as delete or remove. Keep the label specific; do not rely on color alone. |
+| `warning` | Warning | Actions that need caution but are not strictly destructive, such as "Review warnings". |
+`IconButtonShell` also supports `tone="dangerGhost"` for compact destructive icon
+actions. It keeps icon-button sizing while applying destructive hover treatment.
+### Sizes
+`Button` and `ButtonLink` accept `size` values such as `default`, `sm`, `lg`,
+`pill`, `icon`, and `iconPill`. `IconButtonShell` fixes toolbar-friendly
+`h-10 w-10` icon sizing and should be used for compact icon-only controls.
+## Loading buttons
+Pass `loading` to `Button` (including `IconButtonShell`) when an action is in
+progress:
+- Sets `aria-busy="true"` and disables the control to prevent duplicate activation.
+- Preserves the accessible name from visible text or `aria-label`.
+- Renders a centered spinner overlay while keeping label content in the accessibility tree.
+Do not attach separate click handlers that ignore the disabled state while
+`loading` is true.
+## Icon-only accessibility
+Icon-only buttons must expose a clear accessible name:
+- Prefer visible text when space allows.
+- Otherwise provide `aria-label` with a specific action name such as
+  `"Refresh jobs"` or `"Export dashboard"`.
+- Mark decorative icons with `aria-hidden="true"` so screen readers use the
+  button label only.
+`IconButtonShell` inherits the `h-11 w-11` / toolbar touch target from the
+shared button size tokens. Avoid shrinking icon-only controls below the package
+defaults unless the host design system documents an exception.
+## Host application responsibilities
+The component package owns presentation: markup, semantic tones, focus rings,
+loading overlays, and token-backed styling.
+Host applications own:
+- **Action copy** — button labels, `aria-label` text, and confirmation messaging.
+- **Click handlers** — business logic, validation, and error handling.
+- **Routing** — `href` values, client-side navigation, and download targets for `ButtonLink`.
+- **Domain workflows** — when an action is enabled, loading, or destructive in product context.
+Pass data and callbacks into button primitives as props. Do not expect the
+package to read app stores, routers, or API layers.
+## Storybook examples
+Package Storybook stories demonstrate expected states with package imports only:
+- `Primitives/Button/Semantic variants` — normal, disabled, destructive, warning,
+  and link-like examples.
+- `Primitives/Button/Loading and icon only` — loading, focus-visible, icon-only,
+  and destructive icon shell examples.
+Run `bun run storybook` from `ui/packages/components` or inspect the static
+build with `bun run build-storybook`.