playbook_ui 18.2.0 → 18.3.0.pre.alpha.PLAY3342advancedtablereactmulticolumnselectablerow21082

data/app/pb_kits/playbook/pb_form/docs/_form_defaults_react.md

@@ -0,0 +1,29 @@
+Toggle pills to add or remove inputs from the form. Submit to see values for the selected fields on the right. The code snippet updates to match the current selection.
+
+The form calls `useForm()` with `defaultValues` only — `shouldUnregister` is left at its default (`false`). A field's value therefore stays in form state when its pill is turned off, and is restored if the pill is turned back on. Deselected fields are removed in `onSubmit` instead, so only the selected fields appear in the submitted payload.
+
+Every field is bound through `Controller`. A few kits need special handling because their `onChange` (or `onClick`) doesn't fire a DOM event, and their stored shape isn't a plain string.
+
+### Kits that emit non-string values
+
+`Dropdown`, `Select`, `Typeahead`, and `Multi Level Select` need a little extra care, because the value they emit isn't always a plain string.
+
+- **`Dropdown`** calls `onChange({ target: { name, value } })`. For a single-select Dropdown, `event.target.value` is the selected option **node** (`{ id, label, value }`). For a multi-select Dropdown, it's an **array of nodes**. Store that node (or array) in form state so `value={field.value}` feeds the same shape back to the component — the Dropdown compares by `id` / `value` / `label` to determine which option is selected.
+
+  ```jsx
+  <Controller
+    control={control}
+    name="country"
+    render={({ field, fieldState }) => (
+      <Dropdown
+          error={fieldState.error?.message}
+          label="Country"
+          onChange={(event) => field.onChange(event.target.value)}
+          options={countryOptions}
+          requiredIndicator
+          value={field.value}
+      />
+    )}
+    rules={{ validate: (value) => Boolean(value?.value || value?.label) || "Please select a country" }}
+  />
+  ```

data/app/pb_kits/playbook/pb_form/docs/_form_loading.jsx

@@ -0,0 +1,75 @@
+import React, { useEffect, useRef, useState } from "react"
+
+import Button from "../../pb_button/_button"
+import Flex from "../../pb_flex/_flex"
+import TextInput from "../../pb_text_input/_text_input"
+
+import { Controller, useForm } from "react-hook-form"
+
+const LOADING_MS = 5000
+
+const FormLoading = () => {
+  const [loading, setLoading] = useState(false)
+  const timeoutRef = useRef(null)
+  const { control, handleSubmit, reset } = useForm({
+    defaultValues: { exampleTextField: "" },
+  })
+
+  // Clear any pending timeout on unmount so switching to another playground
+  // example mid-loading doesn't call setState on an unmounted component
+  // (React 17 logs a warning for that).
+  useEffect(() => {
+    return () => {
+      if (timeoutRef.current) {
+        window.clearTimeout(timeoutRef.current)
+        timeoutRef.current = null
+      }
+    }
+  }, [])
+
+  const onSubmit = () => {
+    setLoading(true)
+    // If the user submits again before the previous timeout fires, drop the
+    // old one so only the latest submit controls when `loading` flips back.
+    if (timeoutRef.current) window.clearTimeout(timeoutRef.current)
+    timeoutRef.current = window.setTimeout(() => {
+      setLoading(false)
+      timeoutRef.current = null
+    }, LOADING_MS)
+  }
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <Controller
+          control={control}
+          name="exampleTextField"
+          render={({ field }) => (
+            <TextInput
+                label="Example text field"
+                onChange={(event) => field.onChange(event.target.value)}
+                value={field.value}
+            />
+          )}
+      />
+      <Flex gap="xs"
+          marginTop="sm"
+      >
+        <Button
+            disabled={loading}
+            htmlType="submit"
+            loading={loading}
+            text="Submit"
+        />
+        <Button
+            disabled={loading}
+            htmlType="button"
+            onClick={() => reset()}
+            text="Cancel"
+            variant="secondary"
+        />
+      </Flex>
+    </form>
+  )
+}
+
+export default FormLoading

data/app/pb_kits/playbook/pb_form/docs/{_form_loading.md → _form_loading_rails.md}

@@ -1 +1,2 @@
 Pass `loading: true` on `pb_form_with` so submit shows a spinner and disables the submit and cancel buttons. Press Submit in the example to see that state for a few seconds (demo-only script; production forms keep the loading state until navigation or your own reset).
+

data/app/pb_kits/playbook/pb_form/docs/_form_loading_react.md

@@ -0,0 +1 @@
+Keep a `loading` flag in state. On submit, pass `loading` to the submit button so it shows a spinner, and set `disabled` on the submit and cancel buttons. Press Submit in the example to see that state for a few seconds. In a real form, clear `loading` when your request finishes.

data/app/pb_kits/playbook/pb_form/docs/_form_model_values.jsx

@@ -0,0 +1,147 @@
+import React, { useState } from "react"
+
+import Button from "../../pb_button/_button"
+import Card from "../../pb_card/_card"
+import DatePicker from "../../pb_date_picker/_date_picker"
+import Dropdown from "../../pb_dropdown/_dropdown"
+import Flex from "../../pb_flex/_flex"
+import PhoneNumberInput from "../../pb_phone_number_input/_phone_number_input"
+import TextInput from "../../pb_text_input/_text_input"
+
+import { Controller, useForm } from "react-hook-form"
+
+const STATUS_OPTIONS = [
+  { id: "status-open", label: "Open", value: "open" },
+  { id: "status-closed", label: "Closed", value: "closed" },
+]
+
+const OPEN_STATUS = STATUS_OPTIONS[0]
+
+const SERVER_ERRORS = {
+  name: "Name cannot contain emoji",
+  spots: "Spots must be 20 or fewer",
+  startsAt: "Starts at must be before ends at",
+}
+
+const FormModelValues = () => {
+  const [resetKey, setResetKey] = useState(0)
+  const { control, handleSubmit, reset } = useForm({
+    defaultValues: {
+      endsAt: "08/20/2026",
+      name: "Gary 🎉",
+      phone: "5551234567",
+      spots: 42,
+      startsAt: "08/22/2026",
+      status: OPEN_STATUS,
+    },
+  })
+
+  const onReset = () => {
+    reset()
+    setResetKey((current) => current + 1)
+  }
+
+  return (
+    <Card padding="md"
+        shadow="deep"
+    >
+      <form onSubmit={handleSubmit(() => undefined)}>
+        <Controller
+            control={control}
+            name="name"
+            render={({ field }) => (
+              <TextInput
+                  error={SERVER_ERRORS.name}
+                  label="Name"
+                  onChange={(event) => field.onChange(event.target.value)}
+                  value={field.value}
+              />
+            )}
+        />
+        <Controller
+            control={control}
+            name="spots"
+            render={({ field }) => (
+              <TextInput
+                  error={SERVER_ERRORS.spots}
+                  label="Spots"
+                  onChange={(event) => field.onChange(event.target.value)}
+                  type="number"
+                  value={field.value}
+              />
+            )}
+        />
+        <Controller
+            control={control}
+            name="startsAt"
+            render={({ field }) => (
+              <DatePicker
+                  defaultDate={field.value}
+                  error={SERVER_ERRORS.startsAt}
+                  initializeOnce
+                  key={`starts-at-${resetKey}`}
+                  label="Starts at"
+                  onChange={(dateStr) => field.onChange(dateStr)}
+                  pickerId="form-model-starts-at"
+              />
+            )}
+        />
+        <Controller
+            control={control}
+            name="endsAt"
+            render={({ field }) => (
+              <DatePicker
+                  defaultDate={field.value}
+                  initializeOnce
+                  key={`ends-at-${resetKey}`}
+                  label="Ends at"
+                  onChange={(dateStr) => field.onChange(dateStr)}
+                  pickerId="form-model-ends-at"
+              />
+            )}
+        />
+        <Controller
+            control={control}
+            name="status"
+            render={({ field }) => (
+              <Dropdown
+                  key={`status-${resetKey}`}
+                  label="Status"
+                  onChange={(event) => field.onChange(event.target.value)}
+                  options={STATUS_OPTIONS}
+                  value={field.value}
+              />
+            )}
+        />
+        <Controller
+            control={control}
+            name="phone"
+            render={({ field }) => (
+              <PhoneNumberInput
+                  initialCountry="us"
+                  key={`phone-${resetKey}`}
+                  label="Phone"
+                  onChange={(data) => field.onChange(data?.number || "")}
+                  value={field.value}
+              />
+            )}
+        />
+        <Flex gap="xs"
+            marginTop="sm"
+        >
+          <Button htmlType="submit"
+              text="Submit"
+          />
+          <Button
+              htmlType="button"
+              onClick={onReset}
+              text="Cancel"
+              variant="secondary"
+          />
+        </Flex>
+      </form>
+    </Card>
+  )
+}
+
+export default FormModelValues

data/app/pb_kits/playbook/pb_form/docs/_form_model_values_react.md

@@ -0,0 +1,16 @@
+This example is an edit form after a failed server validation. React kits do not read a model, so pass saved values through `useForm({ defaultValues })` and pass each server error string to the kit's `error` prop.
+
+| Kit | Initial value | Error |
+| --- | --- | --- |
+| Text Input / Textarea / Select | `defaultValues` | `error` |
+| Date Picker | `defaultDate` | `error` |
+| Time Picker | `defaultTime` | `error` |
+| Dropdown | `defaultValue` (an option object from `options`) | `error` |
+| Multi Level Select | `selectedIds` | `error` |
+| Phone Number Input | `value` | `error` |
+| Typeahead | `defaultValue` (an option object or array) | `error` |
+| Star Rating | n/a — interactive rating is set only via `onClick`; a prefilled value is not displayed | n/a |
+
+**Notes**
+- Dropdown and Typeahead need the full option object (`{ label, value }`), not a bare id. Look up the option in `options` before passing it.
+- To map errors from a server response into react-hook-form, call `setError(name, { message })` and read `fieldState.error` or `formState.errors`.

data/app/pb_kits/playbook/pb_form/docs/_form_multi_column.jsx

@@ -0,0 +1,164 @@
+import React, { useState } from "react"
+
+import Body from "../../pb_body/_body"
+import Button from "../../pb_button/_button"
+import Caption from "../../pb_caption/_caption"
+import Card from "../../pb_card/_card"
+import Flex from "../../pb_flex/_flex"
+import FlexItem from "../../pb_flex/_flex_item"
+import TextInput from "../../pb_text_input/_text_input"
+
+import { Controller, useForm } from "react-hook-form"
+
+const CODE_PREVIEW = `const { control, handleSubmit } = useForm({
+  defaultValues: { firstName: "", lastName: "" },
+})
+
+<form onSubmit={handleSubmit(onSubmit)}>
+  <Flex gap="sm" wrap>
+    <FlexItem grow>
+      <Controller
+          control={control}
+          name="firstName"
+          render={({ field }) => (
+            <TextInput
+                label="First Name"
+                onChange={(event) => field.onChange(event.target.value)}
+                value={field.value}
+            />
+          )}
+      />
+    </FlexItem>
+    <FlexItem grow>
+      <Controller
+          control={control}
+          name="lastName"
+          render={({ field }) => (
+            <TextInput
+                label="Last Name"
+                onChange={(event) => field.onChange(event.target.value)}
+                value={field.value}
+            />
+          )}
+      />
+    </FlexItem>
+  </Flex>
+  <Button htmlType="submit" text="Submit" />
+  <Button htmlType="button" onClick={onReset} text="Cancel" variant="secondary" />
+</form>`
+
+const textField = (field, label) => (
+  <TextInput
+      label={label}
+      onChange={(event) => field.onChange(event.target.value)}
+      value={field.value}
+  />
+)
+
+const FormMultiColumn = () => {
+  const [submittedData, setSubmittedData] = useState(null)
+  const { control, handleSubmit, reset } = useForm({
+    defaultValues: { firstName: "", lastName: "" },
+  })
+
+  const onReset = () => {
+    reset()
+    setSubmittedData(null)
+  }
+
+  return (
+    <div>
+      <Flex align="stretch"
+          gap="md"
+          wrap
+      >
+        <Flex
+            align="stretch"
+            htmlOptions={{ style: { flex: "2 1" } }}
+            orientation="column"
+        >
+          <Card
+              htmlOptions={{ style: { minWidth: 0 } }}
+              padding="md"
+              shadow="deep"
+          >
+            <form onSubmit={handleSubmit(setSubmittedData)}>
+              <Flex gap="sm"
+                  wrap
+              >
+                <FlexItem grow>
+                  <Controller
+                      control={control}
+                      name="firstName"
+                      render={({ field }) => textField(field, "First Name")}
+                  />
+                </FlexItem>
+                <FlexItem grow>
+                  <Controller
+                      control={control}
+                      name="lastName"
+                      render={({ field }) => textField(field, "Last Name")}
+                  />
+                </FlexItem>
+              </Flex>
+              <Flex gap="xs"
+                  marginTop="sm"
+              >
+                <Button htmlType="submit"
+                    text="Submit"
+                />
+                <Button
+                    htmlType="button"
+                    onClick={onReset}
+                    text="Cancel"
+                    variant="secondary"
+                />
+              </Flex>
+            </form>
+          </Card>
+        </Flex>
+
+        <Flex
+            align="stretch"
+            htmlOptions={{ style: { flex: "1 1" } }}
+            orientation="column"
+        >
+          <Caption marginBottom="xs"
+              text="Submitted Form Data"
+          />
+          <Card background="light"
+              padding="md"
+          >
+            {submittedData ? (
+              <pre style={{ fontSize: "12px", lineHeight: 1.5, margin: 0, overflow: "auto", whiteSpace: "pre-wrap" }}>
+                {JSON.stringify(submittedData, null, 2)}
+              </pre>
+            ) : (
+              <Body color="light"
+                  text="No data submitted yet."
+              />
+            )}
+          </Card>
+        </Flex>
+      </Flex>
+
+      <Body
+          color="light"
+          marginBottom="sm"
+          marginTop="sm"
+          text="Submit the form to see the data on the right."
+      />
+
+      <Card background="dark"
+          dark
+          padding="none"
+      >
+        <pre style={{ fontSize: "12px", lineHeight: 1.5, margin: 0, overflow: "auto", padding: "16px", whiteSpace: "pre" }}>
+          {CODE_PREVIEW}
+        </pre>
+      </Card>
+    </div>
+  )
+}
+
+export default FormMultiColumn

data/app/pb_kits/playbook/pb_form/docs/_form_multi_column_react.md

@@ -0,0 +1,3 @@
+Place related fields side by side with `Flex` and `FlexItem` (`grow`) inside the form. On narrower screens the row wraps so fields stack.
+
+For a fixed-width area such as a Filter Popover, you still want Flex `gap` and usually `wrap`, but you typically do not need extra responsive flex orientation props for viewport breakpoints, because the popover width is the constraint rather than the screen size.