@edux-design/forms 0.0.5 → 0.0.7

package/README.md

@@ -0,0 +1,179 @@
+# @edux-design/forms
+
+React form primitives that share a common context so every label, control, and validation message stays connected and accessible. The package powers the `Field`, `Label`, `Input`, `Textarea`, `Checkbox`, `Radio`, `Switch`, and `Feedback` components used across the Edux design system.
+
+- **Accessible by default** – the `FieldProvider` wires `htmlFor`, `aria-describedby`, and live regions automatically.
+- **Composable** – mix any primitives inside `<Field>` and re-export `Field.Feedback` for colocated messaging.
+- **Design-token aware** – components rely on the shared utility `cx` helper plus the Edux tokens for borders, colors, spacing, and focus rings.
+- **Feature complete inputs** – variants, start/end icons, clear buttons, and controlled/uncontrolled support ship in every text control.
+
+---
+
+## Installation
+
+```bash
+npm install @edux-design/forms @edux-design/utils @edux-design/icons
+# or
+pnpm add @edux-design/forms @edux-design/utils @edux-design/icons
+```
+
+Peer dependencies:
+
+- `react` `^19.1.0`
+- `react-dom` `^19.1.0`
+
+After installing, ensure your build pipeline can consume both ESM and CJS outputs (generated via `tsup`). The published bundle exposes `/dist/index.{js,mjs}` plus type declarations.
+
+---
+
+## Quick Start
+
+```jsx
+import { Field, Label, Input, Textarea, Checkbox, Radio } from "@edux-design/forms";
+
+export function SignupForm() {
+  return (
+    <form className="flex flex-col gap-8 w-full max-w-md">
+      <Field>
+        <Label hint="required" description="We’ll only email account alerts.">
+          Email address
+        </Label>
+        <Input
+          type="email"
+          placeholder="you@example.com"
+          variant="primary"
+          clearable
+        />
+        <Field.Feedback tone="error">
+          This email is already registered.
+        </Field.Feedback>
+      </Field>
+
+      <Field>
+        <Label hint="optional">Bio</Label>
+        <Textarea rows={5} placeholder="Tell us about yourself…" />
+      </Field>
+
+      <Field>
+        <Label>Contact me</Label>
+        <Radio />
+      </Field>
+
+      <Field>
+        <Label hint="required">Terms</Label>
+        <Checkbox aria-label="Agree to the terms and conditions" />
+        <Field.Feedback tone="corrective">
+          Agreeing is required before continuing.
+        </Field.Feedback>
+      </Field>
+    </form>
+  );
+}
+```
+
+Every `Field` instance mounts a internal context. `Label`, `Input`, `Textarea`, `Radio`, and `Field.Feedback` consume that context so they stay synchronized even if rendered in separate components.
+
+---
+
+## Components
+
+### `<Field>`
+
+- Provides layout (`flex`, `gap-8`) and context wiring.
+- Accepts any children; typically wraps `Label`, a control (`Input`, `Textarea`, `Radio`), and optional `Field.Feedback`.
+- Set `orientation="horizontal"` when you need inline layouts (e.g., Switch + label) without affecting other form groups.
+- Re-exports `Field.Feedback` for ergonomic composition.
+
+### `<Label>`
+
+- Consumes the field context and sets `htmlFor`.
+- Supports `hint="required" | "optional"` and a `description` prop rendered beneath the main label.
+- Pass `hidden` to visually hide the label while keeping it accessible.
+
+### `<Input>`
+
+- Extends standard `<input>` props and forwards refs.
+- Variants: `primary`, `error`, `corrective`, `success`, `inactive`.
+- Optional `startIcon`, `endIcon`, and `clearable` button (uses the `Close` icon).
+- When `clearable` is set, clicking the clear button dispatches `onChange` with an empty value, so controlled inputs update seamlessly.
+- Honors `aria-invalid`, `aria-disabled`, and disables itself for the `inactive` variant.
+
+### `<Textarea>`
+
+- Mirrors the Input API while targeting multiline content.
+- Supports `rows`, `startIcon`, `endIcon`, `clearable`, and the same variants.
+- Uses `resize-y` by default; pass inline styles to opt into both-axis resizing.
+
+### `<Radio>`
+
+- Minimal radio control bound to the surrounding `Field` context.
+- Implements hover, focus, and checked states with Tailwind utility classes.
+- Currently exposes a single style; future work will add “active” token colors (see FIXME in source).
+
+### `<Checkbox>`
+
+- Square control that mirrors native checkbox behavior while layering on design-token driven states (hover, focus, pressed, inactive, and error).
+- Supports the same variants as text inputs plus an `indeterminate` appearance for tri-state flows.
+- Automatically shares IDs and `aria-describedby` references with the wrapping `Field`, so helper text and validation copy are announced.
+- Pairs well with `<Label>` for field titles; pass `aria-label` or wrap inline helper text next to the component when you need per-option copy.
+
+### `<Switch>`
+
+- Toggle-style checkbox that maps the native input to Edux track and thumb visuals, complete with iconography that switches between the Close and Check glyphs.
+- Variants mirror the checkbox control (`primary`, `success`, `corrective`, `error`, `inactive`) so validation states stay consistent.
+- Integrates with the `Field` context to automatically sync `id`, focus management, and `aria-describedby` strings built from registered feedback messages.
+- Disables itself automatically when `variant="inactive"` and exposes hover, focus, pressed, and checked states for every other variant.
+
+### `<Field.Feedback>`
+
+- Semantic messaging component with tones: `info`, `success`, `warning`, `error`, `corrective`.
+- Registers its `id` with the parent `Field`, so any controls automatically receive `aria-describedby`.
+- `tone="error"` switches to `role="alert"` / `aria-live="assertive"`; other tones stay `aria-live="polite"`.
+- Includes a circular icon container that colors itself based on the selected tone.
+
+---
+
+## Accessibility Model
+
+1. **Context-generated IDs** – `FieldProvider` assigns a unique `labelHTMLForId`; the same ID drives `<label htmlFor>` and the child control’s `id`.
+2. **Description registry** – `Field.Feedback` registers/unregisters its identifier so inputs build the `aria-describedby` string automatically, even if multiple feedback blocks mount.
+3. **Live regions** – error messages announce immediately via `role="alert"`, while neutral/success tones fall back to polite announcements.
+4. **Focus styling** – every interactive element shares the branded `focus:shadow-focus` utility, ensuring visible focus outlines without extra work.
+
+To enforce the contract, hooks throw if you render any primitive outside `<Field>`, making misconfigurations obvious during development.
+
+---
+
+## Theming & Variants
+
+Variants map directly to semantic tokens defined in `@edux-design/design-tokens` and consumed via Tailwind utility classes:
+
+| Variant      | Border / Background intent                                     |
+| ------------ | -------------------------------------------------------------- |
+| `primary`    | Default border; highlights on hover/focus with primary color.  |
+| `error`      | Danger border + subtle danger background for immediate errors. |
+| `corrective` | Soft highlight for “nudge” messages without blocking input.    |
+| `success`    | Success border for confirmed entries.                          |
+| `inactive`   | Muted border/background, disables the control automatically.   |
+
+Apply variants per control to reflect validation state. Combine with `Field.Feedback` to reinforce messaging.
+
+---
+
+## Building & Contributing
+
+- `pnpm build` (or `npm run build`) bundles the package via `tsup` into `dist/`.
+- `pnpm dev` starts `tsup` in watch mode.
+- `pnpm lint` and `pnpm check-types` keep code quality high.
+
+Stories live under `src/demos/*.stories.jsx`; use them as references for new component states and to manually verify visual behavior.
+
+---
+
+## Roadmap / Known Gaps
+
+- Radio buttons need dedicated “active” token colors (tracked via FIXME in `Radio.jsx`).
+- Feedback icons currently reuse the `Close` glyph for all tones; alternative glyphs per tone may improve clarity.
+- Clear button animations exist, but the components still rely on manually passing `value` for controlled usage—add tests to prevent regressions.
+
+Contributions should follow the existing Tailwind utility conventions and rely on the shared tokens/utilities package to stay consistent with the broader system.

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
 
 declare function Label({ children, hint, description, ...props }: {
     children: React.ReactNode;
@@ -58,6 +59,20 @@ type InputProps = React.InputHTMLAttributes<HTMLInputElement> & {
 
 declare function Radio(): react_jsx_runtime.JSX.Element;
 
+declare const Checkbox: react.ForwardRefExoticComponent<react.RefAttributes<any>>;
+
+/**
+ * Switch component.
+ *
+ * Renders an accessible checkbox styled as a switch/toggle that plugs into the
+ * `Field` context so labeling and descriptions stay in sync.
+ *
+ * @typedef {React.InputHTMLAttributes<HTMLInputElement> & {
+ *   variant?: "primary"|"success"|"corrective"|"error"|"inactive",
+ * }} SwitchProps
+ */
+declare const Switch: react.ForwardRefExoticComponent<react.RefAttributes<any>>;
+
 /**
  * Props for the Textarea component.
  *
@@ -141,7 +156,7 @@ type TextareaProps = React.TextareaHTMLAttributes<HTMLTextAreaElement> & {
  * @returns {React.ReactElement}
  */
 declare function Feedback({ id, tone, children, className, ...rest }: FeedbackProps): React.ReactElement;
-declare function Field({ children }: FieldProps): React.ReactElement;
+declare function Field({ children, orientation, className, }: FieldProps): React.ReactElement;
 declare namespace Field {
     export { Feedback };
 }
@@ -184,4 +199,28 @@ type FieldProps = {
     children: React.ReactNode;
 };
 
-export { Feedback, Field, Input, Label, Radio, Textarea };
+declare const Option: react.ForwardRefExoticComponent<react.RefAttributes<any>>;
+
+/**
+ * Accessible Combobox built with the existing Input + Popover primitives.
+ *
+ * @typedef {Object} ComboboxProps
+ * @property {React.ReactNode} children - Collection of `<Option>` items.
+ * @property {string|string[]} [value] - controlled selected value(s)
+ * @property {string|string[]|null} [defaultValue=null] - uncontrolled default selection
+ * @property {(value: string|string[], option: { value: string, label: string }) => void} [onValueChange] - selection handler
+ * @property {string} [placeholder] - input placeholder text
+ * @property {boolean} [disabled=false] - disables the combobox
+ * @property {boolean} [autoComplete=false] - enables type-ahead filtering when true
+ * @property {boolean} [selectOnly=false] - hides freeform typing so users must pick from the list
+ * @property {boolean} [multiSelect=false] - allows selecting multiple options
+ * @property {string} [emptyState] - text shown when no results match
+ * @property {(option: { value: string, label: string }, query: string) => boolean} [filterFunction] - custom filter logic (used when filtering is active)
+ * @property {string} [wrapperClassName] - optional class for the outer wrapper
+ * @property {string} [contentClassName] - optional class for the popover content
+ * @property {string} [listClassName] - optional class for the list element
+ * @property {string} [optionClassName] - optional class for each option
+ */
+declare const ComboboxRoot: react.ForwardRefExoticComponent<react.RefAttributes<any>>;
+
+export { Checkbox, ComboboxRoot as Combobox, Option as ComboboxOption, Feedback, Field, Input, Label, Option, Radio, Switch, Textarea };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
 
 declare function Label({ children, hint, description, ...props }: {
     children: React.ReactNode;
@@ -58,6 +59,20 @@ type InputProps = React.InputHTMLAttributes<HTMLInputElement> & {
 
 declare function Radio(): react_jsx_runtime.JSX.Element;
 
+declare const Checkbox: react.ForwardRefExoticComponent<react.RefAttributes<any>>;
+
+/**
+ * Switch component.
+ *
+ * Renders an accessible checkbox styled as a switch/toggle that plugs into the
+ * `Field` context so labeling and descriptions stay in sync.
+ *
+ * @typedef {React.InputHTMLAttributes<HTMLInputElement> & {
+ *   variant?: "primary"|"success"|"corrective"|"error"|"inactive",
+ * }} SwitchProps
+ */
+declare const Switch: react.ForwardRefExoticComponent<react.RefAttributes<any>>;
+
 /**
  * Props for the Textarea component.
  *
@@ -141,7 +156,7 @@ type TextareaProps = React.TextareaHTMLAttributes<HTMLTextAreaElement> & {
  * @returns {React.ReactElement}
  */
 declare function Feedback({ id, tone, children, className, ...rest }: FeedbackProps): React.ReactElement;
-declare function Field({ children }: FieldProps): React.ReactElement;
+declare function Field({ children, orientation, className, }: FieldProps): React.ReactElement;
 declare namespace Field {
     export { Feedback };
 }
@@ -184,4 +199,28 @@ type FieldProps = {
     children: React.ReactNode;
 };
 
-export { Feedback, Field, Input, Label, Radio, Textarea };
+declare const Option: react.ForwardRefExoticComponent<react.RefAttributes<any>>;
+
+/**
+ * Accessible Combobox built with the existing Input + Popover primitives.
+ *
+ * @typedef {Object} ComboboxProps
+ * @property {React.ReactNode} children - Collection of `<Option>` items.
+ * @property {string|string[]} [value] - controlled selected value(s)
+ * @property {string|string[]|null} [defaultValue=null] - uncontrolled default selection
+ * @property {(value: string|string[], option: { value: string, label: string }) => void} [onValueChange] - selection handler
+ * @property {string} [placeholder] - input placeholder text
+ * @property {boolean} [disabled=false] - disables the combobox
+ * @property {boolean} [autoComplete=false] - enables type-ahead filtering when true
+ * @property {boolean} [selectOnly=false] - hides freeform typing so users must pick from the list
+ * @property {boolean} [multiSelect=false] - allows selecting multiple options
+ * @property {string} [emptyState] - text shown when no results match
+ * @property {(option: { value: string, label: string }, query: string) => boolean} [filterFunction] - custom filter logic (used when filtering is active)
+ * @property {string} [wrapperClassName] - optional class for the outer wrapper
+ * @property {string} [contentClassName] - optional class for the popover content
+ * @property {string} [listClassName] - optional class for the list element
+ * @property {string} [optionClassName] - optional class for each option
+ */
+declare const ComboboxRoot: react.ForwardRefExoticComponent<react.RefAttributes<any>>;
+
+export { Checkbox, ComboboxRoot as Combobox, Option as ComboboxOption, Feedback, Field, Input, Label, Option, Radio, Switch, Textarea };