@you-agent-factory/components 0.0.0

package/docs/forms-input-primitives.md

@@ -0,0 +1,311 @@
+# Form input primitives
+
+Domain-free text input, textarea, checkbox, and file input controls for reusable
+forms. Use these primitives when you need accessible native form semantics with
+package styling, without importing dashboard features, API clients, or app state.
+
+These components are **presentation controls**. They render styled native inputs
+and forward standard React form props. They do not fetch data, perform validation,
+upload files, or own durable application state.
+
+## Required setup
+
+Import package styles once in your host application before rendering primitives:
+
+```css
+@import "@you-agent-factory/components/styles.css";
+```
+
+Primitives depend on package role tokens 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 forms category entrypoint for tree-shaking and explicit category
+boundaries:
+
+```ts
+import {
+  PackageCheckbox,
+  PackageFileInput,
+  PackageInput,
+  PackageTextarea,
+  inputVariants,
+  textareaVariants,
+} from "@you-agent-factory/components/forms";
+```
+
+The same exports are also available from the package root:
+
+```ts
+import { PackageInput } from "@you-agent-factory/components";
+```
+
+## Host ownership
+
+The package owns presentation markup, focus rings, disabled styling, and native
+control semantics. Host applications own everything domain-specific:
+
+| Concern | Owner |
+| --- | --- |
+| Visible labels and placeholder copy | Host |
+| Helper text and validation error messages | Host |
+| `id`, `name`, `required`, and `disabled` values | Host |
+| `aria-describedby`, `aria-invalid`, and `aria-label` wiring | Host |
+| Controlled value or checked state | Host (when using controlled mode) |
+| Form submission, validation rules, and error mapping | Host |
+| File upload, persistence, and storage side effects | Host |
+| Selected-file display copy (for example helper text) | Host |
+| Data fetching, caching, and durable cross-route state | Host |
+
+Pass values, handlers, and accessibility attributes into primitives as props.
+Do not expect primitives to read from your routers, stores, or API layers.
+
+## Controlled versus uncontrolled values
+
+All four primitives forward native React form props. Choose the mode that matches
+how your host form manages state.
+
+### Text input (`PackageInput`)
+
+| Mode | When to use | Key props |
+| --- | --- | --- |
+| Controlled | Host state must mirror every keystroke (live validation, dependent fields, reset) | `value` + `onChange` |
+| Uncontrolled | Native form submission or refs are enough; host does not need per-keystroke state | `defaultValue` + optional `ref` |
+
+```tsx
+import { useState } from "react";
+import { PackageInput } from "@you-agent-factory/components/forms";
+
+export function ControlledNameField() {
+  const [name, setName] = useState("");
+
+  return (
+    <PackageInput
+      aria-label="Display name"
+      onChange={(event) => {
+        setName(event.target.value);
+      }}
+      value={name}
+    />
+  );
+}
+
+export function UncontrolledNameField() {
+  return (
+    <PackageInput
+      aria-label="Display name"
+      defaultValue="Initial name"
+      name="displayName"
+    />
+  );
+}
+```
+
+Do not pass both `value` and `defaultValue` on the same control.
+
+### Textarea (`PackageTextarea`)
+
+Same controlled/uncontrolled rules as text input. `PackageTextarea` also accepts
+`variant`:
+
+- `field` (default) — bordered field shell with scrollable body (`textareaVariants`).
+- `plain` — borderless transparent textarea for embedding inside custom shells.
+
+### Checkbox (`PackageCheckbox`)
+
+| Mode | When to use | Key props |
+| --- | --- | --- |
+| Controlled | Host must react to every toggle (conditional sections, select-all logic) | `checked` + `onChange` |
+| Uncontrolled | Checkbox state can live in the native form until submit | `defaultChecked` + optional `ref` |
+
+The visible check indicator is decorative (`aria-hidden`). Assistive technology
+reads the native `input type="checkbox"` inside the component. Always provide an
+accessible name with a visible `<label htmlFor={id}>`, `aria-label`, or
+`aria-labelledby`.
+
+### File input (`PackageFileInput`)
+
+| Mode | When to use | Key props |
+| --- | --- | --- |
+| Controlled selection tracking | Host must show selected-file feedback or gate submit buttons | Read `event.target.files` in `onChange`; optionally clear with `value=""` on re-render |
+| Uncontrolled | File selection is handled entirely by native form submit | `name` on the input; read files from `FormData` on submit |
+
+The primitive opens the native file picker and exposes selected `File` objects
+through standard `onChange` events. It does **not** upload, persist, or validate
+file contents. Display selected file names in host-owned helper text or adjacent
+copy when your UX requires feedback.
+
+```tsx
+import { useState } from "react";
+import { PackageFileInput } from "@you-agent-factory/components/forms";
+
+export function CoverImageField() {
+  const [selectedName, setSelectedName] = useState<string | undefined>();
+
+  return (
+    <>
+      <PackageFileInput
+        accept="image/png,image/jpeg"
+        aria-describedby="cover-image-helper"
+        id="cover-image"
+        onChange={(event) => {
+          setSelectedName(event.target.files?.[0]?.name);
+        }}
+      />
+      <p id="cover-image-helper">
+        {selectedName ? `Selected: ${selectedName}` : "PNG or JPEG up to 2 MB."}
+      </p>
+    </>
+  );
+}
+```
+
+## Labels, descriptions, and error relationships
+
+Primitives render the control only. Host applications wire labels and supporting
+text:
+
+1. Generate stable `id` values (for example `useId()`).
+2. Associate visible labels with `<label htmlFor={controlId}>`.
+3. Render helper text in an element with its own `id`.
+4. Render error text in an element with `role="alert"` and its own `id`.
+5. Pass `aria-describedby` listing helper and/or error element ids.
+6. Pass `aria-invalid={true}` when the field fails validation.
+
+```tsx
+import { useId } from "react";
+import { PackageInput } from "@you-agent-factory/components/forms";
+
+export function NameField({
+  errorText,
+  helperText,
+  invalid,
+  value,
+  onChange,
+}: {
+  errorText?: string;
+  helperText?: string;
+  invalid?: boolean;
+  value: string;
+  onChange: (value: string) => void;
+}) {
+  const reactId = useId();
+  const controlId = `${reactId}-control`;
+  const helperId = helperText ? `${reactId}-helper` : undefined;
+  const errorId = errorText ? `${reactId}-error` : undefined;
+  const describedBy =
+    [helperId, errorId].filter(Boolean).join(" ") || undefined;
+
+  return (
+    <div>
+      <label htmlFor={controlId}>Display name</label>
+      <PackageInput
+        aria-describedby={describedBy}
+        aria-invalid={invalid || Boolean(errorText) || undefined}
+        id={controlId}
+        onChange={(event) => {
+          onChange(event.target.value);
+        }}
+        value={value}
+      />
+      {helperText ? <p id={helperId}>{helperText}</p> : null}
+      {errorText ? (
+        <p id={errorId} role="alert">
+          {errorText}
+        </p>
+      ) : null}
+    </div>
+  );
+}
+```
+
+Package Storybook uses `PackageFormStoryField` for the same wiring pattern in
+demos. That helper is story support only; host applications should compose
+labels and messages in their own form-field layer.
+
+## Required, disabled, and invalid state
+
+| State | Host responsibility | Primitive behavior |
+| --- | --- | --- |
+| `required` | Set `required` when the field must be submitted | Native constraint validation semantics |
+| `disabled` | Set `disabled` to block interaction | Pointer and keyboard changes are ignored; disabled styling and semantics apply |
+| Invalid | Set `aria-invalid={true}` when validation fails | Danger border and focus ring via `aria-invalid` styles |
+| Error copy | Render error text and link with `aria-describedby` | Does not invent error messages |
+
+Disabled file inputs ignore `onChange` and keep an empty `files` list until
+re-enabled.
+
+## Accessibility expectations
+
+- Text input, textarea, and file input expose visible `focus-visible` rings for
+  keyboard users.
+- Checkbox keyboard focus targets the native input; the styled indicator shows a
+  focus ring via `peer-focus-visible` styles.
+- Invalid states use `aria-invalid` styling on the native control (checkbox uses
+  `peer-aria-invalid` on the indicator).
+- Host-supplied header actions, labels, and error text must use accessible names
+  and programmatic relationships (`htmlFor`, `aria-describedby`, `role="alert"`).
+- Do not rely on placeholder text as the only accessible name.
+
+## Variant helpers
+
+`inputVariants` and `textareaVariants` export the shared field class strings for
+host compositions that need matching shells around sibling elements:
+
+```ts
+import { inputVariants, textareaVariants } from "@you-agent-factory/components/forms";
+```
+
+## Storybook visual reference
+
+Package Storybook lives under `Forms/PackageInput`, `Forms/PackageTextarea`,
+`Forms/PackageCheckbox`, and `Forms/PackageFileInput`. Stories use package
+imports and package token decorators only — no dashboard providers.
+
+| Primitive | Example stories |
+| --- | --- |
+| `PackageInput` | Controlled, Uncontrolled, Disabled, Invalid, ErrorState, Focus, HelperText, MobileWidth |
+| `PackageTextarea` | Controlled, Uncontrolled, Disabled, Invalid, ErrorState, Focus, HelperText, MobileWidth |
+| `PackageCheckbox` | Controlled, Uncontrolled, Disabled, Invalid, ErrorState, Focus, HelperText, MobileWidth |
+| `PackageFileInput` | Default, Disabled, Invalid, ErrorState, Focus, HelperText, SelectedFile, MobileWidth |
+
+Run package Storybook locally:
+
+```bash
+cd ui/packages/components
+bun run storybook
+```
+
+Browser verification for responsive and focus stories:
+
+```bash
+cd ui/packages/components
+bun run verify:storybook-browser
+```
+
+## Allowed dependencies
+
+Primitive 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
+
+Primitive source must **not** import:
+
+- Dashboard feature modules, routes, or providers
+- Generated OpenAPI clients or dashboard API adapters
+- React Query, Zustand, Monaco, Sonner, or dashboard i18n/session providers
+- Factory, work, session, or provider domain types
+
+`check:package-boundary` enforces these rules in CI.
+
+## Dashboard integration note
+
+The dashboard re-exports these primitives from `components/ui` (`Input`,
+`Textarea`, `Checkbox`, `FileInput`) so existing feature imports keep working
+while resolving to package implementations. New host applications should import
+directly from `@you-agent-factory/components` or
+`@you-agent-factory/components/forms`.

package/docs/forms-select-primitives.md

@@ -0,0 +1,362 @@
+# Form select primitives
+
+Domain-free select controls for reusable forms. Use these primitives when you need
+accessible combobox or native `<select>` semantics with package styling, without
+importing dashboard features, API clients, generated OpenAPI types, or app
+localization providers.
+
+The package ships three layers:
+
+| Component | Role |
+| --- | --- |
+| `Select` primitives | Radix-backed combobox building blocks (`Select`, `SelectTrigger`, `SelectContent`, `SelectItem`, and helpers). |
+| `NativeSelect` | Styled native `<select>` for simple option lists and progressive enhancement. |
+| `EnumSelect` helpers | Opinionated wrappers that map host-supplied option arrays into `Select` markup. |
+
+These components are **presentation controls**. They render styled select UI and
+forward standard React props. They do not fetch options, perform validation,
+localize labels, or own durable application state.
+
+## Required setup
+
+Import package styles once in your host application before rendering selects:
+
+```css
+@import "@you-agent-factory/components/styles.css";
+```
+
+Select primitives depend on package role tokens 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 forms category entrypoint for tree-shaking and explicit category
+boundaries:
+
+```ts
+import {
+  EnumSelect,
+  ENUM_SELECT_EMPTY_VALUE,
+  NativeSelect,
+  OptionalEnumSelect,
+  ResetEnumSelect,
+  Select,
+  SELECT_EMPTY_STATE_VALUE,
+  SelectContent,
+  SelectEmpty,
+  SelectField,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+  type EnumSelectOption,
+} from "@you-agent-factory/components/forms";
+```
+
+The same exports are also available from the package root:
+
+```ts
+import {
+  EnumSelect,
+  NativeSelect,
+  Select,
+} from "@you-agent-factory/components";
+```
+
+## Host ownership
+
+The package owns presentation markup, focus rings, disabled styling, keyboard
+interaction, and combobox semantics. Host applications own everything
+domain-specific:
+
+| Concern | Owner |
+| --- | --- |
+| Option values and visible labels | Host |
+| Placeholder, empty, and loading copy | Host |
+| Visible labels, helper text, and validation errors | Host |
+| `id`, `disabled`, and `aria-*` wiring | Host |
+| Controlled `value` and `open` state | Host (when using controlled mode) |
+| `onValueChange` and `onOpenChange` handlers | Host |
+| Fetching, caching, and refreshing option lists | Host |
+| Localization and enum label mapping | Host |
+| Form submission, validation rules, and error mapping | Host |
+
+Pass data and callbacks into select components as props. Do not expect the
+package to read from your routers, stores, or API layers.
+
+## Option contract
+
+### `EnumSelectOption`
+
+`EnumSelect`, `OptionalEnumSelect`, and `ResetEnumSelect` accept a readonly
+array of domain-free options:
+
+```ts
+type EnumSelectOption = {
+  value: string;
+  label: string;
+  disabled?: boolean;
+};
+```
+
+| Field | Contract |
+| --- | --- |
+| `value` | Stable string identifier used in `onValueChange`. Must be unique within the option list. |
+| `label` | Host-supplied visible text. The package does not translate or format enum values. |
+| `disabled` | When `true`, the option is not selectable by pointer or keyboard and exposes disabled semantics to assistive technology. |
+
+### Empty option lists
+
+When `options` is empty and `loading` is `false`, `EnumSelect` renders a
+non-selectable `SelectEmpty` row using `emptyOptionsLabel` (default:
+`"No options available"`). The row is a disabled menu item backed by
+`SELECT_EMPTY_STATE_VALUE`, so users cannot accidentally select a fake value.
+
+For custom Radix compositions, render `SelectEmpty` inside `SelectContent`
+instead of mapping interactive `SelectItem` rows over an empty array.
+
+### Optional and reset helpers
+
+| Helper | Use when |
+| --- | --- |
+| `OptionalEnumSelect` | The host needs a nullable selection. Uses `ENUM_SELECT_EMPTY_VALUE` as a dedicated empty row and maps it back to `null` in `onValueChange`. |
+| `ResetEnumSelect` | The host needs a select that always returns to the placeholder after each selection (for example one-shot filters). Remounts internally after each change. |
+
+## Controlled value and open state
+
+`Select` forwards Radix `Select.Root` props. Choose controlled or uncontrolled
+mode based on how your host form manages state.
+
+### Controlled value
+
+Use controlled value when host state must mirror the current selection (dependent
+fields, validation, reset, or async reconciliation):
+
+```tsx
+import { useState } from "react";
+import {
+  EnumSelect,
+  type EnumSelectOption,
+} from "@you-agent-factory/components/forms";
+
+const options: EnumSelectOption[] = [
+  { label: "Story", value: "story" },
+  { label: "Task", value: "task" },
+];
+
+function WorkTypeField() {
+  const [value, setValue] = useState("story");
+
+  return (
+    <EnumSelect
+      id="work-type"
+      onValueChange={setValue}
+      options={options}
+      placeholder="Select a work type"
+      value={value}
+    />
+  );
+}
+```
+
+Host responsibilities for controlled value:
+
+- Provide the current `value` on every render.
+- Update host state inside `onValueChange` when the user selects a different
+  **enabled** option.
+- Expect `onValueChange` not to fire when the user re-selects the current value
+  or activates a disabled option.
+
+### Controlled open
+
+Use controlled open when the host must coordinate menu visibility with other UI
+(for example closing on route change or synchronizing with a parent disclosure):
+
+```tsx
+import { useState } from "react";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@you-agent-factory/components/forms";
+
+function ControlledOpenExample() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Select onOpenChange={setOpen} open={open} value="story">
+      <SelectTrigger aria-label="Work type">
+        <SelectValue placeholder="Select a work type" />
+      </SelectTrigger>
+      <SelectContent>
+        <SelectItem value="story">Story</SelectItem>
+      </SelectContent>
+    </Select>
+  );
+}
+```
+
+Host responsibilities for controlled open:
+
+- Provide the current `open` boolean on every render.
+- Update host state inside `onOpenChange` when the user opens or closes the
+  menu.
+
+### Uncontrolled usage
+
+Omit `value` and `open` to let Radix manage internal state. `defaultValue` still
+sets the initial selection. Prefer controlled mode when host validation or
+cross-field logic depends on the current selection.
+
+## Keyboard behavior and focus
+
+Radix select primitives provide combobox semantics on the trigger:
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` / `Shift+Tab` | Move focus to and from the trigger. |
+| `Space`, `Enter`, `ArrowDown`, `ArrowUp` | Open the menu when closed. |
+| `ArrowDown` / `ArrowUp` | Move highlight across enabled options while open. |
+| `Enter` / `Space` | Select the highlighted enabled option and close the menu. |
+| `Escape` | Close the menu without changing the selection. |
+| `Home` / `End` | Jump to the first or last enabled option while open. |
+
+After a successful selection, focus returns to the trigger. Package styles keep
+`focus-visible` rings on the trigger and highlighted menu items during keyboard
+interaction.
+
+`NativeSelect` uses native platform keyboard behavior for `<select>` elements.
+
+## Disabled behavior
+
+| Surface | Behavior |
+| --- | --- |
+| Disabled field (`disabled` on `Select` or `EnumSelect`) | Trigger is not interactive, exposes disabled semantics, and cannot open the menu. |
+| Disabled option (`disabled` on `SelectItem` or `EnumSelectOption`) | Skipped by keyboard navigation and not selectable by pointer. |
+| Loading `EnumSelect` (`loading`) | Trigger is disabled, sets `aria-busy`, and shows `loadingLabel` as the placeholder. Controlled value is routed through `SELECT_EMPTY_STATE_VALUE` so the loading label stays visible. |
+
+## Loading and empty states
+
+`EnumSelect` supports asynchronous option loading without dashboard wiring:
+
+```tsx
+<EnumSelect
+  id="work-type"
+  loading={isLoading}
+  loadingLabel="Loading work types..."
+  emptyOptionsLabel="No work types available"
+  onValueChange={setValue}
+  options={options}
+  value={value}
+/>
+```
+
+While `loading` is `true`:
+
+- The trigger is disabled and marked busy.
+- The menu shows a non-selectable `SelectEmpty` row with `loadingLabel`.
+- Host `value` is not shown in the trigger; the loading label takes precedence.
+
+When loading completes and `options` is still empty, `emptyOptionsLabel` is used
+for both the menu affordance and the visible empty state.
+
+## Error and description relationships
+
+Use host-owned helper and error text with explicit ARIA relationships on the
+trigger. `SelectField` is a small layout helper when you want label, description,
+and error regions colocated with the control:
+
+```tsx
+import {
+  Select,
+  SelectContent,
+  SelectField,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@you-agent-factory/components/forms";
+
+function WorkTypeField({ error }: { error?: string }) {
+  const controlId = "work-type";
+  const helperId = "work-type-helper";
+  const errorId = "work-type-error";
+
+  return (
+    <SelectField
+      description="Choose the work type for this request."
+      descriptionId={helperId}
+      error={error}
+      errorId={errorId}
+      inputId={controlId}
+      label="Work type"
+    >
+      <Select value="story">
+        <SelectTrigger
+          aria-describedby={`${helperId} ${errorId}`}
+          aria-invalid={Boolean(error)}
+          id={controlId}
+        >
+          <SelectValue placeholder="Select a work type" />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="story">Story</SelectItem>
+        </SelectContent>
+      </Select>
+    </SelectField>
+  );
+}
+```
+
+Error text renders with `role="alert"` so assistive technology announces
+validation failures without relying on color alone. Wire `aria-describedby` to
+both helper and error element ids when both are present.
+
+## Long labels and compact layouts
+
+`SelectTrigger` clamps the selected value with `line-clamp-1`. `SelectItem` text
+uses `line-clamp-2` with `break-words` so long option labels stay inside the
+menu without overlapping neighboring UI. Prefer concise labels in product copy,
+but the package constrains overflow for narrow containers and mobile widths.
+
+## NativeSelect
+
+Use `NativeSelect` when a native `<select>` is acceptable and you only need
+package field styling:
+
+```tsx
+import { NativeSelect } from "@you-agent-factory/components/forms";
+
+function PriorityField() {
+  return (
+    <NativeSelect aria-label="Priority" defaultValue="medium" id="priority">
+      <option value="low">Low</option>
+      <option value="medium">Medium</option>
+      <option value="high">High</option>
+    </NativeSelect>
+  );
+}
+```
+
+`NativeSelect` forwards standard `<select>` props. Host applications still own
+`<option>` children, labels, validation messaging, and change handlers.
+
+## Storybook examples
+
+Package Storybook stories demonstrate expected states with package imports only.
+Run `bun run storybook` from `ui/packages/components` or inspect the static
+build with `bun run build-storybook`.
+
+| Story | What it shows |
+| --- | --- |
+| `Forms/PackageSelect/ControlledValue` | Host-controlled selection |
+| `Forms/PackageSelect/ControlledOpen` | Host-controlled menu open state |
+| `Forms/PackageSelect/KeyboardInteraction` | Keyboard open, navigate, select, and focus return |
+| `Forms/PackageSelect/DisabledField` | Disabled trigger |
+| `Forms/PackageSelect/EmptyOptions` | Non-selectable empty menu affordance |
+| `Forms/PackageSelect/LoadingOptions` | Loading trigger and menu state |
+| `Forms/PackageSelect/ErrorState` | `aria-invalid` and visible error text |
+| `Forms/PackageSelect/LongLabel` | Long labels at desktop width |
+| `Forms/PackageSelect/LongLabelMobile` | Long labels at mobile width |