@servicetitan/anvil2-ext-common 0.3.20 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @servicetitan/anvil2-ext-common
 
+## 0.5.0
+
+### Minor Changes
+
+- [#2386](https://github.com/servicetitan/hammer/pull/2386) [`efd6121`](https://github.com/servicetitan/hammer/commit/efd6121759713cefb12e51387183bc97c0c3aec6) Thanks [@hbartlett-st](https://github.com/hbartlett-st)! - [Suggestions] Add new render-prop component that coordinates highlighting fields populated by a suggestion until they are edited. Exposes `suggestable` and `suggestor` prop-getters plus imperative `markSuggested`, `clearHighlight`, and `isHighlighted` methods.
+
+### Patch Changes
+
+- [#2417](https://github.com/servicetitan/hammer/pull/2417) [`4c60241`](https://github.com/servicetitan/hammer/commit/4c602418f0fb7da06961e76781b44bac02d0a7d0) Thanks [@hbartlett-st](https://github.com/hbartlett-st)! - [Dependencies] Loosen `@servicetitan/anvil2` dependency to `workspace:^` so consumers resolve a caret range instead of a pinned version
+
+- Updated dependencies [[`efd6121`](https://github.com/servicetitan/hammer/commit/efd6121759713cefb12e51387183bc97c0c3aec6), [`58eb789`](https://github.com/servicetitan/hammer/commit/58eb78970e47ffeabbe57a97c345cdbe8edd4a01), [`1c606c5`](https://github.com/servicetitan/hammer/commit/1c606c5f0bd4d7416cb0f4b6fcb409c4b6377d6b), [`efd6121`](https://github.com/servicetitan/hammer/commit/efd6121759713cefb12e51387183bc97c0c3aec6), [`efd6121`](https://github.com/servicetitan/hammer/commit/efd6121759713cefb12e51387183bc97c0c3aec6)]:
+  - @servicetitan/anvil2@3.2.0
+
+## 0.4.0
+
+### Minor Changes
+
+- [#2393](https://github.com/servicetitan/hammer/pull/2393) [`fa64efa`](https://github.com/servicetitan/hammer/commit/fa64efa889ee2571504fe5ade2dbffc702132c80) Thanks [@pbuckingham-st](https://github.com/pbuckingham-st)! - [Form] Add formstate field-state wrappers (`A2InputFieldState`, `SelectableOptionsFieldState`) and a `Form.*` namespace of `observer` binding components for Anvil2 input fields (TextField, Textarea, NumberField, DateFieldSingle/Range/Yearless/YearlessRange, TimeField, beta Select/MultiSelect/TreeSelect, and RadioGroup/CheckboxGroup). Checkbox/radio are provided as the group wrappers only.
+
+### Patch Changes
+
+- Updated dependencies [[`5e46d4f`](https://github.com/servicetitan/hammer/commit/5e46d4f7760c8f4c3374523f9777f34b61f72270), [`f13b003`](https://github.com/servicetitan/hammer/commit/f13b0036669dc8ba3e566de88374b4487bb9891b), [`f8e27ae`](https://github.com/servicetitan/hammer/commit/f8e27ae598b1a2c4900cd2dc16e6efcb3a11fbb9)]:
+  - @servicetitan/anvil2@3.1.0
+
 ## 0.3.20
 
 ### Patch Changes

package/README.md

@@ -25,6 +25,33 @@ Components and hooks can be imported as named exports from the package root:
 import { useConfirmDialog } from "@servicetitan/anvil2-ext-common";
 ```
 
+### Form field-state wrappers (`Form.*`)
+
+`Form.*` components bind Anvil2 fields to a `formstate`-based `A2InputFieldState`, eliminating boilerplate for value, onChange, error, and warning wiring.
+
+**Quick example:**
+
+```tsx
+import { A2InputFieldState } from "@servicetitan/anvil2-ext-common";
+import { Form } from "@servicetitan/anvil2-ext-common";
+
+const name = new A2InputFieldState("");
+
+<Form.TextField fieldState={name} label="Name" />;
+```
+
+Available wrappers: `Form.TextField`, `Form.Textarea`, `Form.NumberField`, `Form.DateFieldSingle`, `Form.DateFieldRange`, `Form.DateFieldYearless`, `Form.DateFieldYearlessRange`, `Form.TimeField`, `Form.Select`, `Form.MultiSelect`, `Form.TreeSelect`, `Form.RadioGroup`, `Form.CheckboxGroup`.
+
+Checkbox and radio inputs are provided as the **group** wrappers (`Form.RadioGroup`, `Form.CheckboxGroup`) only. A standalone Anvil2 `Checkbox`/`Radio` exposes a boolean error (styling) with no message area, so it can't surface validation errors/warnings — the group is the form pattern that renders a `FieldMessage`.
+
+`Form.Select`, `Form.MultiSelect`, and `Form.TreeSelect` wrap the beta Anvil2 components and are exported from the package root alongside the rest of the `Form.*` namespace. `Form.Select` and `Form.MultiSelect` support all loader modes (eager, page-lazy, offset-lazy, group-lazy) — pass a `loadOptions` function appropriate to your loader strategy.
+
+**Known limitations:**
+
+- Single checkbox/radio inputs have no standalone wrapper — use `Form.CheckboxGroup` / `Form.RadioGroup` (the Anvil2 group is the component that renders validation messages).
+- `updateMode` is primarily meaningful for value-update controls (TextField, Textarea, NumberField).
+- The following Anvil2 input types have no `Form.*` wrapper: SearchField, InputMask, Switch, ButtonToggle, SelectCard, Combobox, SegmentedControl, RichTextEditor.
+
 <br />
 
 # Contribution Guide

package/dist/Suggestions-ChGGcGuO.js

@@ -0,0 +1,47 @@
+import { jsx, Fragment } from 'react/jsx-runtime';
+import { useState, useRef } from 'react';
+
+const wrap = (handlers, before) => {
+  if (!handlers) {
+    return {};
+  }
+  const out = {};
+  for (const name of Object.keys(handlers)) {
+    const fn = handlers[name];
+    out[name] = (...args) => {
+      before();
+      fn?.(...args);
+    };
+  }
+  return out;
+};
+function Suggestions({ children }) {
+  const [suggested, setSuggested] = useState(
+    () => /* @__PURE__ */ new Set()
+  );
+  const registry = useRef(/* @__PURE__ */ new Set());
+  const markSuggested = (keys) => setSuggested(new Set(keys ?? [...registry.current]));
+  const clearHighlight = (key) => setSuggested((prev) => {
+    if (!prev.has(key)) return prev;
+    const next = new Set(prev);
+    next.delete(key);
+    return next;
+  });
+  const api = {
+    suggestable: (key, handlers) => {
+      registry.current.add(key);
+      return {
+        isHighlighted: suggested.has(key),
+        ...wrap(handlers, () => clearHighlight(key))
+      };
+    },
+    suggestor: (handlers, keys) => wrap(handlers, () => markSuggested(keys)),
+    markSuggested,
+    clearHighlight,
+    isHighlighted: (key) => suggested.has(key)
+  };
+  return /* @__PURE__ */ jsx(Fragment, { children: children(api) });
+}
+
+export { Suggestions as S };
+//# sourceMappingURL=Suggestions-ChGGcGuO.js.map

package/dist/Suggestions-ChGGcGuO.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Suggestions-ChGGcGuO.js","sources":["../src/components/Suggestions/Suggestions.tsx"],"sourcesContent":["import { ReactNode, useRef, useState } from \"react\";\n\n/* eslint-disable @typescript-eslint/no-explicit-any -- prop getters are\n * intentionally field-agnostic: they wrap whatever change handlers a given\n * field exposes (onChange, onSelectedOptionChange, ...) without caring about\n * their argument shapes. */\ntype Handler = (...args: any[]) => void;\ntype Handlers = Record<string, Handler | undefined>;\n\nexport interface SuggestionsApi {\n  /**\n   * Props for a field that should be highlighted while it holds a suggested\n   * value. Returns `isHighlighted` plus copies of any handlers you pass, each\n   * wrapped to clear the highlight on the first user edit. Pass the handler\n   * under the field's own prop name (`onChange`, `onSelectedOptionChange`, ...).\n   *\n   * @example <TextField {...suggestable(\"city\", { onChange: setCity })} />\n   */\n  suggestable: <O extends Handlers>(\n    key: string,\n    handlers?: O,\n  ) => { isHighlighted: boolean } & O;\n  /**\n   * Props for the field whose selection populates the others. Returns copies of\n   * the handlers you pass, each wrapped to first mark the suggestable fields as\n   * highlighted. Your handler still does the value population.\n   *\n   * @param keys which fields to highlight; defaults to every registered key.\n   * @example <TypeaheadTextField {...suggestor({ onSelectOption: apply })} />\n   */\n  suggestor: <O extends Handlers>(handlers?: O, keys?: string[]) => O;\n  /** Imperatively highlight fields (defaults to every registered key). */\n  markSuggested: (keys?: string[]) => void;\n  /** Imperatively clear a field's highlight. */\n  clearHighlight: (key: string) => void;\n  /** Whether a field is currently holding a suggested value. */\n  isHighlighted: (key: string) => boolean;\n}\n\nexport interface SuggestionsProps {\n  children: (api: SuggestionsApi) => ReactNode;\n}\n\nconst wrap = <O extends Handlers>(\n  handlers: O | undefined,\n  before: () => void,\n): O => {\n  if (!handlers) {\n    return {} as O;\n  }\n\n  const out: Handlers = {};\n  for (const name of Object.keys(handlers)) {\n    const fn = handlers[name];\n    out[name] = (...args) => {\n      before();\n      fn?.(...args);\n    };\n  }\n  return out as O;\n};\n\n/**\n * Coordinates the \"highlight fields populated by a suggestion until edited\"\n * behavior for a group of fields, without per-field state wiring.\n *\n * Relies on the fact that a controlled field's change handler fires only on\n * user input, never when its `value` prop changes programmatically — so we\n * track provenance per field rather than comparing values. A field stays\n * un-highlighted after an edit even if the suggested value is re-entered,\n * because typing still fires the handler.\n *\n * @example\n * <Suggestions>\n *   {({ suggestor, suggestable }) => (\n *     <>\n *       <TypeaheadTextField\n *         {...suggestor({ onSelectOption: (opt) => applyAddress(opt.value) })}\n *         loadOptions={lookupAddresses}\n *       />\n *       <TextField {...suggestable(\"city\", { onChange: handleCity })} />\n *     </>\n *   )}\n * </Suggestions>\n */\nexport function Suggestions({ children }: SuggestionsProps) {\n  const [suggested, setSuggested] = useState<ReadonlySet<string>>(\n    () => new Set(),\n  );\n  const registry = useRef<Set<string>>(new Set());\n\n  const markSuggested = (keys?: string[]) =>\n    setSuggested(new Set(keys ?? [...registry.current]));\n\n  const clearHighlight = (key: string) =>\n    setSuggested((prev) => {\n      if (!prev.has(key)) return prev; // keep referential stability\n      const next = new Set(prev);\n      next.delete(key);\n      return next;\n    });\n\n  const api: SuggestionsApi = {\n    suggestable: (key, handlers) => {\n      registry.current.add(key); // learn keys so markSuggested() can target all\n      return {\n        isHighlighted: suggested.has(key),\n        ...wrap(handlers, () => clearHighlight(key)),\n      };\n    },\n    suggestor: (handlers, keys) => wrap(handlers, () => markSuggested(keys)),\n    markSuggested,\n    clearHighlight,\n    isHighlighted: (key) => suggested.has(key),\n  };\n\n  return <>{children(api)}</>;\n}\n"],"names":[],"mappings":";;;AA2CA,MAAM,IAAA,GAAO,CACX,QAAA,EACA,MAAA,KACM;AACN,EAAA,IAAI,CAAC,QAAA,EAAU;AACb,IAAA,OAAO,EAAC;AAAA,EACV;AAEA,EAAA,MAAM,MAAgB,EAAC;AACvB,EAAA,KAAA,MAAW,IAAA,IAAQ,MAAA,CAAO,IAAA,CAAK,QAAQ,CAAA,EAAG;AACxC,IAAA,MAAM,EAAA,GAAK,SAAS,IAAI,CAAA;AACxB,IAAA,GAAA,CAAI,IAAI,CAAA,GAAI,CAAA,GAAI,IAAA,KAAS;AACvB,MAAA,MAAA,EAAO;AACP,MAAA,EAAA,GAAK,GAAG,IAAI,CAAA;AAAA,IACd,CAAA;AAAA,EACF;AACA,EAAA,OAAO,GAAA;AACT,CAAA;AAyBO,SAAS,WAAA,CAAY,EAAE,QAAA,EAAS,EAAqB;AAC1D,EAAA,MAAM,CAAC,SAAA,EAAW,YAAY,CAAA,GAAI,QAAA;AAAA,IAChC,0BAAU,GAAA;AAAI,GAChB;AACA,EAAA,MAAM,QAAA,GAAW,MAAA,iBAAoB,IAAI,GAAA,EAAK,CAAA;AAE9C,EAAA,MAAM,aAAA,GAAgB,CAAC,IAAA,KACrB,YAAA,CAAa,IAAI,GAAA,CAAI,IAAA,IAAQ,CAAC,GAAG,QAAA,CAAS,OAAO,CAAC,CAAC,CAAA;AAErD,EAAA,MAAM,cAAA,GAAiB,CAAC,GAAA,KACtB,YAAA,CAAa,CAAC,IAAA,KAAS;AACrB,IAAA,IAAI,CAAC,IAAA,CAAK,GAAA,CAAI,GAAG,GAAG,OAAO,IAAA;AAC3B,IAAA,MAAM,IAAA,GAAO,IAAI,GAAA,CAAI,IAAI,CAAA;AACzB,IAAA,IAAA,CAAK,OAAO,GAAG,CAAA;AACf,IAAA,OAAO,IAAA;AAAA,EACT,CAAC,CAAA;AAEH,EAAA,MAAM,GAAA,GAAsB;AAAA,IAC1B,WAAA,EAAa,CAAC,GAAA,EAAK,QAAA,KAAa;AAC9B,MAAA,QAAA,CAAS,OAAA,CAAQ,IAAI,GAAG,CAAA;AACxB,MAAA,OAAO;AAAA,QACL,aAAA,EAAe,SAAA,CAAU,GAAA,CAAI,GAAG,CAAA;AAAA,QAChC,GAAG,IAAA,CAAK,QAAA,EAAU,MAAM,cAAA,CAAe,GAAG,CAAC;AAAA,OAC7C;AAAA,IACF,CAAA;AAAA,IACA,SAAA,EAAW,CAAC,QAAA,EAAU,IAAA,KAAS,KAAK,QAAA,EAAU,MAAM,aAAA,CAAc,IAAI,CAAC,CAAA;AAAA,IACvE,aAAA;AAAA,IACA,cAAA;AAAA,IACA,aAAA,EAAe,CAAC,GAAA,KAAQ,SAAA,CAAU,IAAI,GAAG;AAAA,GAC3C;AAEA,EAAA,uBAAO,GAAA,CAAA,QAAA,EAAA,EAAG,QAAA,EAAA,QAAA,CAAS,GAAG,CAAA,EAAE,CAAA;AAC1B;;;;"}

package/dist/Suggestions.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/Suggestions.js

@@ -0,0 +1,2 @@
+export { S as Suggestions, S as default } from './Suggestions-ChGGcGuO.js';
+//# sourceMappingURL=Suggestions.js.map

package/dist/Suggestions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Suggestions.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}