@sharedex/ui 0.9.0 → 0.10.0

package/dist/schema/types.d.ts

@@ -135,7 +135,7 @@ export interface EffectValue {
     readonly options: Readonly<Record<string, unknown>>;
 }
 /** The groups of configurable pieces. */
-export declare const SCHEMA_FAMILIES: readonly ["background", "transition", "reveal", "carousel-layout", "carousel-modifier", "carousel-presence", "carousel-open", "carousel-physics", "carousel", "ticker", "grid", "grid-open", "scroll", "button", "text", "word-cycle", "typewriter", "number-roll"];
+export declare const SCHEMA_FAMILIES: readonly ["background", "transition", "reveal", "carousel-layout", "carousel-modifier", "carousel-presence", "carousel-open", "carousel-physics", "carousel", "ticker", "grid", "grid-open", "scroll", "button", "text", "word-cycle", "typewriter", "number-roll", "form"];
 export type SchemaFamily = (typeof SCHEMA_FAMILIES)[number];
 /** Where a factory is imported from. */
 export type SchemaEntry = "@sharedex/ui" | "@sharedex/ui/three";
@@ -147,7 +147,7 @@ export interface SchemaMeta {
     readonly family?: string;
     /** The weakest device it runs smoothly on: all, mid, high. */
     readonly tier?: string;
-    /** Where it can play (transitions: `carousel`, `reveal`). */
+    /** Where it can play (transitions: `carousel`, `reveal`; form effects: the controls they fit, `field`, `checkbox` …). */
     readonly modes?: readonly string[];
 }
 /** One configurable piece. */

package/dist/schema/types.js

@@ -24,4 +24,5 @@ export const SCHEMA_FAMILIES = [
     "word-cycle",
     "typewriter",
     "number-roll",
+    "form",
 ];

package/guides/README.md

@@ -1,61 +1,62 @@
-# @sharedex/ui section guides (for Claude Code)
-
-One guide per headless section. Read the guide for a section before building or
-restyling it. They ship inside the package, so they always match the installed
-version: `node_modules/@sharedex/ui/guides/<section>.md`.
-
-| Section | Guide |
-|---|---|
-| Hero | [hero.md](hero.md) |
-| About | [about.md](about.md) |
-| Services | [services.md](services.md) |
-| Contact | [contact.md](contact.md) |
-| Backgrounds (any section) | [backgrounds.md](backgrounds.md) |
-| Transitions (reveals, slideshows, scroll effects) | [transitions.md](transitions.md) |
-| Galleries: 3D carousels, Ticker, Grid | [gallery.md](gallery.md) |
-| Buttons and their effects (any section's actions) | [buttons.md](buttons.md) |
-| Text effects (titles, eyebrows, cycling words, rolling figures) | [text.md](text.md) |
-
-## Rules for every section
-
-- **Layout and content come from the package; the look comes from the project.**
-  Pick the layout with the `layout` prop and pass the client's real copy in
-  `content`. Don't rebuild a section from scratch with divs.
-- **The default look reads only the `sx-*` tokens.** In a project generated by
-  the sharedex Design System Builder, `design/theme.css` already points them at
-  the project's brand, so sections match before you change anything.
-- **Configured pieces are already in `design/effects.ts`** (in a project the
-  builder generated): the primary buttons' effects, backgrounds, reveals,
-  slideshow looks, carousel configs, and the props of tickers, grids and scroll
-  effects, the headings' text effects (`titleEffects`, `eyebrowEffects`), as
-  named constants.
-  Import them by the names `design/page-plan.md` uses and spread or pass them
-  as it shows; don't re-create them, and never call an effect factory during
-  render (a new object every render restarts it).
-- **Server Components (Next.js App Router)**: sections, CSS / SVG / image
-  backgrounds, reveals and scroll effects work in a Server Component. Carousels,
-  slideshows, Tickers and Grids take functions as children, and canvas / WebGL /
-  Three.js backgrounds are programs: a page using them is `"use client"`, or
-  keeps them in a client component of its own.
-- **Restyle with `className` on any part.** Defaults sit in Tailwind's
-  `components` layer; your utility classes always win. Never use `!important`.
-- **`unstyled` on `Root`** removes every visual default and keeps the layout.
-  Use it only when the design differs from the default in most parts.
-- **`background` on `Root`** takes a decorative layer, usually
-  `<Background.Root effect={…} />`. It sits behind the content automatically.
-  See [backgrounds.md](backgrounds.md) for picking an effect.
-- **`reveal` on `Root`** makes the main parts appear one after another when the
-  section scrolls into view: `reveal` (fadeUp), `reveal={blurFade()}`, or
-  `reveal={{ effect, stagger, delay }}`. See [transitions.md](transitions.md).
-- **`actionEffect` on `Hero.Root`** turns the actions into `Button`s, the first
-  wearing the effects. See [buttons.md](buttons.md).
-- **`titleEffect` / `eyebrowEffect` on every `Root`** put text effects on the
-  title and the eyebrow; the Hero's `titleWords` + `titleCycle` add a cycling
-  word, About's `statRoll` rolls the figures. See [text.md](text.md).
-- **Compose parts to change structure**: render `<X.Root>` with your own
-  children and place the parts (and your own elements) in the order you need.
-- **Layouts respond to the section's own width** (container queries), not the
-  viewport. Don't add breakpoint classes to change a layout's column count;
-  pick another layout instead.
-- **RTL works through logical properties.** Use `ms-*`/`me-*`/`ps-*`/`pe-*` and
-  `text-start`/`text-end` in your own classes too.
+# @sharedex/ui section guides (for Claude Code)
+
+One guide per headless section. Read the guide for a section before building or
+restyling it. They ship inside the package, so they always match the installed
+version: `node_modules/@sharedex/ui/guides/<section>.md`.
+
+| Section | Guide |
+|---|---|
+| Hero | [hero.md](hero.md) |
+| About | [about.md](about.md) |
+| Services | [services.md](services.md) |
+| Contact | [contact.md](contact.md) |
+| Backgrounds (any section) | [backgrounds.md](backgrounds.md) |
+| Transitions (reveals, slideshows, scroll effects) | [transitions.md](transitions.md) |
+| Galleries: 3D carousels, Ticker, Grid | [gallery.md](gallery.md) |
+| Buttons and their effects (any section's actions) | [buttons.md](buttons.md) |
+| Text effects (titles, eyebrows, cycling words, rolling figures) | [text.md](text.md) |
+| Forms: every control, the wiring, form effects | [forms.md](forms.md) |
+
+## Rules for every section
+
+- **Layout and content come from the package; the look comes from the project.**
+  Pick the layout with the `layout` prop and pass the client's real copy in
+  `content`. Don't rebuild a section from scratch with divs.
+- **The default look reads only the `sx-*` tokens.** In a project generated by
+  the sharedex Design System Builder, `design/theme.css` already points them at
+  the project's brand, so sections match before you change anything.
+- **Configured pieces are already in `design/effects.ts`** (in a project the
+  builder generated): the primary buttons' effects, backgrounds, reveals,
+  slideshow looks, carousel configs, and the props of tickers, grids and scroll
+  effects, the headings' text effects (`titleEffects`, `eyebrowEffects`), the form
+  controls' effects (`fieldEffects`, `checkboxEffects` …), as named constants.
+  Import them by the names `design/page-plan.md` uses and spread or pass them
+  as it shows; don't re-create them, and never call an effect factory during
+  render (a new object every render restarts it).
+- **Server Components (Next.js App Router)**: sections, CSS / SVG / image
+  backgrounds, reveals and scroll effects work in a Server Component. Carousels,
+  slideshows, Tickers and Grids take functions as children, and canvas / WebGL /
+  Three.js backgrounds are programs: a page using them is `"use client"`, or
+  keeps them in a client component of its own.
+- **Restyle with `className` on any part.** Defaults sit in Tailwind's
+  `components` layer; your utility classes always win. Never use `!important`.
+- **`unstyled` on `Root`** removes every visual default and keeps the layout.
+  Use it only when the design differs from the default in most parts.
+- **`background` on `Root`** takes a decorative layer, usually
+  `<Background.Root effect={…} />`. It sits behind the content automatically.
+  See [backgrounds.md](backgrounds.md) for picking an effect.
+- **`reveal` on `Root`** makes the main parts appear one after another when the
+  section scrolls into view: `reveal` (fadeUp), `reveal={blurFade()}`, or
+  `reveal={{ effect, stagger, delay }}`. See [transitions.md](transitions.md).
+- **`actionEffect` on `Hero.Root`** turns the actions into `Button`s, the first
+  wearing the effects. See [buttons.md](buttons.md).
+- **`titleEffect` / `eyebrowEffect` on every `Root`** put text effects on the
+  title and the eyebrow; the Hero's `titleWords` + `titleCycle` add a cycling
+  word, About's `statRoll` rolls the figures. See [text.md](text.md).
+- **Compose parts to change structure**: render `<X.Root>` with your own
+  children and place the parts (and your own elements) in the order you need.
+- **Layouts respond to the section's own width** (container queries), not the
+  viewport. Don't add breakpoint classes to change a layout's column count;
+  pick another layout instead.
+- **RTL works through logical properties.** Use `ms-*`/`me-*`/`ps-*`/`pe-*` and
+  `text-start`/`text-end` in your own classes too.

package/guides/contact.md

@@ -1,76 +1,99 @@
-# Contact
-
-How to reach the client: details, the project's own form, and an optional map.
-
-```tsx
-import { Contact } from "@sharedex/ui";
-
-<Contact.Root
-  layout="split-info"
-  content={{
-    title: "Come by or get in touch",
-    description: "We answer emails within a day.",
-    details: [
-      { label: "Address", value: "Rua das Flores 12, Lisbon", href: "https://maps.app.goo.gl/…" },
-      { label: "Phone", value: "+351 21 000 0000", href: "tel:+351210000000" },
-      { label: "Email", value: "hello@example.com", href: "mailto:hello@example.com" },
-      { label: "Opening hours", value: "Tue–Sun, 7:00–19:00" },
-    ],
-    map: { src: "https://www.openstreetmap.org/export/embed.html?…", title: "Map of our shop" },
-  }}
->
-  <Contact.Info />
-  <Contact.Form>
-    <ContactForm />   {/* the project's form: fields, validation, sending */}
-  </Contact.Form>
-  <Contact.Map />
-</Contact.Root>
-```
-
-`Contact.Form` is only a slot in the layout. Build the form in the project with
-the project's form conventions and input recipe. Without children, the default
-composition is `Contact.Info` + `Contact.Map` (no form).
-
-## Layouts
-
-| `layout` | Use when |
-|---|---|
-| `split-info` | The standard: details beside the form, map full width below. |
-| `centered` | A short page or no map: one narrow centred column, details in a row. |
-| `map` | Location matters (shop, venue): details and form beside a tall map. |
-
-## Content
-
-```ts
-interface ContactContent {
-  eyebrow?: string;
-  title: string;          // <h2>
-  description?: string;
-  details?: { label: string; value: string; href?: string }[];  // rendered as a <dl>
-  map?: { src: string; title: string };  // an embeddable map URL; title is required for the iframe
-}
-```
-
-## Parts
-
-`Contact.Root` › `Contact.Info` (`Contact.Eyebrow`, `Contact.Title`,
-`Contact.Description`, `Contact.Details`) · `Contact.Form` (slot) ·
-`Contact.Map`.
-
-## Background
-
-`<Contact.Root background={<Background.Root effect={dotPattern()} />}>` draws a decorative layer behind
-the content (the section is its stacking context, so the content needs no z-index). Any effect from
-`@sharedex/ui` works, or from `@sharedex/ui/three` for the Three.js ones. Keep it still or nearly still: people are reading and typing here. Read
-`node_modules/@sharedex/ui/guides/backgrounds.md` before picking one.
-
-## Reveal
-
-`reveal` on `Root` plays a transition on the main parts as the section scrolls into view, once:
-the info, then the form, then the map. `reveal` alone is `fadeUp()`, 0.12 s apart; `reveal={blurFade()}` picks the transition;
-`reveal={{ effect, stagger, delay, duration }}` sets the timing. See
-`node_modules/@sharedex/ui/guides/transitions.md`.
-
+# Contact
+
+How to reach the client: details, the project's own form, and an optional map.
+
+```tsx
+import { Contact } from "@sharedex/ui";
+
+<Contact.Root
+  layout="split-info"
+  content={{
+    title: "Come by or get in touch",
+    description: "We answer emails within a day.",
+    details: [
+      { label: "Address", value: "Rua das Flores 12, Lisbon", href: "https://maps.app.goo.gl/…" },
+      { label: "Phone", value: "+351 21 000 0000", href: "tel:+351210000000" },
+      { label: "Email", value: "hello@example.com", href: "mailto:hello@example.com" },
+      { label: "Opening hours", value: "Tue–Sun, 7:00–19:00" },
+    ],
+    map: { src: "https://www.openstreetmap.org/export/embed.html?…", title: "Map of our shop" },
+  }}
+>
+  <Contact.Info />
+  <Contact.Form>
+    <ContactForm />   {/* the project's form, built from @sharedex/ui's controls */}
+  </Contact.Form>
+  <Contact.Map />
+</Contact.Root>
+```
+
+`Contact.Form` is only a slot in the layout. Build the form in the project, from
+`@sharedex/ui`'s controls, wired the project's way (read
+`node_modules/@sharedex/ui/guides/forms.md`). Without children, the default
+composition is `Contact.Info` + `Contact.Map` (no form).
+
+```tsx
+"use client"; // React Hook Form runs in the browser; the section around it can stay a Server Component
+import { Field, Checkbox, ErrorSummary, Button } from "@sharedex/ui";
+import { fieldEffects, checkboxEffects, primaryButtonEffects } from "@/design/effects"; // those the design picked
+
+export function ContactForm() {
+  const { register, handleSubmit, formState: { errors, submitCount } } = useForm({ resolver, defaultValues, mode: "onTouched", shouldFocusError: false });
+  return (
+    <form noValidate onSubmit={handleSubmit(send)}>
+      <ErrorSummary errors={errors} attempt={submitCount} />
+      <Field label="Email" type="email" autoComplete="email" effect={fieldEffects} error={errors.email?.message} {...register("email")} />
+      <Field as="textarea" label="Message" rows={4} grow counter={1000} effect={fieldEffects} error={errors.message?.message} {...register("message")} />
+      <Checkbox label="I agree to the privacy notice" effect={checkboxEffects} error={errors.privacy?.message} {...register("privacy")} />
+      <Button type="submit" effect={primaryButtonEffects}>Send message</Button>
+    </form>
+  );
+}
+```
+
+After a successful send, `FormSwap` (`look="success"`) swaps the form for the thanks
+message and moves the focus to it, so a screen reader reads it.
+
+## Layouts
+
+| `layout` | Use when |
+|---|---|
+| `split-info` | The standard: details beside the form, map full width below. |
+| `centered` | A short page or no map: one narrow centred column, details in a row. |
+| `map` | Location matters (shop, venue): details and form beside a tall map. |
+
+## Content
+
+```ts
+interface ContactContent {
+  eyebrow?: string;
+  title: string;          // <h2>
+  description?: string;
+  details?: { label: string; value: string; href?: string }[];  // rendered as a <dl>
+  map?: { src: string; title: string };  // an embeddable map URL; title is required for the iframe
+}
+```
+
+## Parts
+
+`Contact.Root` › `Contact.Info` (`Contact.Eyebrow`, `Contact.Title`,
+`Contact.Description`, `Contact.Details`) · `Contact.Form` (slot) ·
+`Contact.Map`.
+
+## Background
+
+`<Contact.Root background={<Background.Root effect={dotPattern()} />}>` draws a decorative layer behind
+the content (the section is its stacking context, so the content needs no z-index). Any effect from
+`@sharedex/ui` works, or from `@sharedex/ui/three` for the Three.js ones. Keep it still or nearly still: people are reading and typing here. Read
+`node_modules/@sharedex/ui/guides/backgrounds.md` before picking one.
+
+## Reveal
+
+`reveal` on `Root` plays a transition on the main parts as the section scrolls into view, once:
+the info, then the form, then the map. `reveal` alone is `fadeUp()`, 0.12 s apart; `reveal={blurFade()}` picks the transition;
+`reveal={{ effect, stagger, delay, duration }}` sets the timing. See
+`node_modules/@sharedex/ui/guides/transitions.md`.
+
 ## Text effects
 
 `titleEffect` and `eyebrowEffect` on `Root` put text effects on the title and the eyebrow (one, or a list that
@@ -78,7 +101,7 @@ stacks): they render as `Text` wearing them. Left out, they stay plain elements.
 System Builder generated, pass the configured constants: `titleEffect={titleEffects}`, `eyebrowEffect={eyebrowEffects}`
 from `design/effects.ts`. Read `node_modules/@sharedex/ui/guides/text.md`.
 
-## Don't
-
-- Don't put the form's submit logic in the section; it lives with the form.
-- Don't embed a map without the client's address confirmed.
+## Don't
+
+- Don't put the form's submit logic in the section; it lives with the form.
+- Don't embed a map without the client's address confirmed.

package/guides/forms.md

@@ -0,0 +1,105 @@
+# Forms
+
+`@sharedex/ui`'s form controls each render the browser's own control (`<input>`, `<textarea>`, `<select>`, a checkbox,
+a radio, a range, a file input) and paint around it. The real control does the work: the label, the keyboard, autofill,
+password managers, screen readers, a plain form submit. Effects are plain descriptions (`inputFloat()`) that stack.
+Don't build inputs by hand.
+
+```tsx
+import { Field, Checkbox, Switch, Select, ErrorSummary, inputFloat, validColor, checkDraw } from "@sharedex/ui";
+
+// module level: an effect made during render is a new object every render
+const fieldEffects = [inputFloat(), validColor()];
+
+<Field label="Email" type="email" effect={fieldEffects} error={errors.email?.message} {...register("email")} />
+<Checkbox label="I agree to the terms" effect={checkDraw()} {...register("terms")} />
+```
+
+In a project generated by the sharedex Design System Builder, the design's effects are ready in `design/effects.ts`,
+one list per kind of control: `fieldEffects` (`Field`, `NumberField`), `checkboxEffects` (`Checkbox`, `CheckGroup`),
+`radioEffects` (`RadioGroup`), `switchEffects` (`Switch`), `pickerEffects` (`Select`, `Combobox`, `TagsField`),
+`rangeEffects` (`Range`); only the ones the design picked exist. Use those; don't pick new ones. The look of fields is
+the design's: pass nothing, or `variant` as `.claude/rules/design-system.md` says.
+
+## The controls
+
+| Need | Control | Value |
+|---|---|---|
+| Text, email, password, a message | `Field` (`as="textarea"`; `clearable`, `reveal`, `counter`, `strength`, `status`, `hint`, `grow`; `inline` inside a sentence) | native: `register` |
+| One choice, on or off | `Checkbox`, `Switch` | native |
+| Several choices | `CheckGroup` (select all, a count), `ChipGroup` (filter chips) | native (a list) |
+| One of a few | `RadioGroup` (cards, segments, stars through effects), `ChipGroup multiple={false}` | native |
+| One of many | `Select` (the real `<select>`) | native |
+| Search, many at once, your own words | `Combobox` (`multiple`, `creatable`, `loading`), `TagsField` | a list: `Controller` |
+| A number | `NumberField` (steps, scrub), `Range` (one or two thumbs) | native (`valueAsNumber`); two thumbs: `Controller` |
+| A one-time code, a PIN | `OtpField` (`mask` for a PIN) | native |
+| Files | `FileDrop` (`accept`, `maxSize`, `maxFiles`, `reorder`, `page`, `progress`) | `File[]`: `Controller` |
+| Errors | `ErrorSummary` (takes the focus on submit), `focusFirstError(form)` | |
+| Flow | `FormSteps` (`Root` / `Step` / `Progress` / `Next` / `Back`), `FormReveal`, `FormSwap` | |
+| Small widgets | `InlineEdit`, `SaveStatus`, `PasswordRules`, `FormBuddy` (a sign-in companion) | |
+
+## Wiring (React Hook Form + Zod)
+
+```tsx
+// the schema is a module-level constant; only the resolver changes, with the language
+const resolver = useMemo(() => zodResolver(schema, { error: makeZodErrorMap(t) }), [t, i18n.language]);
+const { register, control, handleSubmit, formState: { errors, submitCount } } = useForm({
+  resolver, defaultValues, mode: "onTouched", shouldFocusError: false,
+});
+
+<form noValidate onSubmit={handleSubmit(send)}>
+  <ErrorSummary errors={errors} attempt={submitCount} />
+  <Field label={t("name")} effect={fieldEffects} error={errors.name?.message} {...register("name")} />
+  <RadioGroup label={t("plan")} options={plans} error={errors.plan?.message} {...register("plan")} />
+  <Controller name="topics" control={control} render={({ field }) => (
+    <Combobox label={t("topics")} multiple options={topics} error={errors.topics?.message} {...field} />
+  )} />
+  <Controller name="files" control={control} render={({ field }) => (
+    <FileDrop label={t("files")} accept="image/*,.pdf" maxSize={5_000_000} error={errors.files?.message} {...field} />
+  )} />
+</form>
+```
+
+- **Every prop and the `ref` land on the real control**, so `register()` spreads straight onto `Field`, `Checkbox`,
+  `CheckGroup`, `RadioGroup`, `Switch`, `Select`, `ChipGroup`, `OtpField`, `NumberField` and a one-thumb `Range`. A value
+  no native control holds (a list, files) goes through a `Controller`'s `field`, as it is.
+- **The error's words go in `error`.** The control then sets `aria-invalid`, points `aria-describedby` at the message,
+  and announces it. A red line or a shake is never the only signal.
+- `mode: "onTouched"` checks a field when it is first left, then live: the same moment `:user-invalid` picks. Complete
+  `defaultValues`: `""` for text, `false` for a checkbox, `[]` for lists, `undefined` for a radio group.
+- The error map goes in per parse, never through `z.config()` (it is global and would mix languages on a server). The
+  server action re-runs `schema.safeParse(values, { error: makeZodErrorMap(t) })` in the sender's language and returns
+  the first message.
+- **A plain form works too**: every control submits its value by name (lists as several inputs, files in the real file
+  input), and the browser's own checks (`required`, `type`, `pattern`) drive the same error looks.
+- **Files go from the browser to storage** (a signed upload address); the form sends their addresses. `FileDrop`'s
+  `progress(file)` shows how far each got.
+
+## Effects
+
+Each control takes `effect`: one effect or a list; they stack. Effect names start with their control: `input*` and
+`valid*` (Field), `check*`, `radio*`, `switch*`, `picker*` / `list*` / `chipPop` (Select, Combobox, TagsField), `range*`,
+`chip*` (ChipGroup), `file*` (FileDrop), `step*` (FormSteps). A control warns in development about an effect made for
+another one, and about two effects that move the same thing (the last wins: keep one).
+
+- **One look per moment.** A floating label with an underline and a red/green border reads well; five label effects
+  don't.
+- **Server Components:** the controls are client components that a Server Component can render, and almost every
+  effect is plain data. `checkConfetti`, `rangeElastic` and `inputCycle` (unless `vanish: false`) carry code: the
+  component holding them starts with `"use client"`. `FormReveal` needs no client code at all.
+- **Reduced motion** keeps every state (an error's colour and words, a check, a chosen option) and drops the movement.
+  Endless loops (`inputBeam`, `inputSkeleton`, `switchNeon`) pause off screen and with the page's pause switch
+  (`usePauseLoops`).
+
+## Rules
+
+- A real `<label>` for every control (`label`, or `aria-label` where the sentence names it, as with `inline`). A
+  placeholder never replaces a label.
+- Text inputs stay at 16 px or more on phones (the base sheet does it: don't shrink them), so iOS doesn't zoom in.
+- Restyle with `className` (the box you see), `rootClassName` (the whole control), `labelClassName`; your utility
+  classes win over the defaults. `unstyled` drops the look and keeps the structure.
+- Every built-in word ("Show password", "Clear", "No results", "Drop files here") is a `labels` prop: pass it
+  translated.
+- RTL works through logical properties: slides, lines and thumbs follow the reading direction. A code (`OtpField`)
+  always reads left to right.
+- `Contact.Form` is the place for a contact form: see [contact.md](contact.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sharedex/ui",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Headless React components: an animated carousel with pure-function layout effects, page sections (Hero, About, Services, Contact) with layout presets and token-driven default looks, and 88 background effects (CSS, SVG, canvas, WebGL, Three.js) on one cheap runtime.",
   "license": "MIT",
   "author": "Mohamad Faseh <contact@mohamadfaseh.com>",