@impulse-ui-native/form-field 2.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ImpulseUI Native contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @impulse-ui-native/form-field
+
+Accessible label, description, required-state, and validation composition for custom Impulse UI Native controls.
+
+## Installation
+
+```sh
+pnpm add @impulse-ui-native/form-field
+```
+
+Render `FormField` inside `ThemeProvider` from `@impulse-ui-native/theme`.
+
+## Usage
+
+```tsx
+import { FormField } from "@impulse-ui-native/form-field";
+import { Switch } from "@impulse-ui-native/switch";
+
+<FormField
+  label="Notifications"
+  description="Receive updates about your account."
+  required
+  error={notificationError}
+>
+  {({ controlProps }) => (
+    <Switch
+      {...controlProps}
+      checked={notificationsEnabled}
+      onCheckedChange={setNotificationsEnabled}
+    />
+  )}
+</FormField>;
+```
+
+The render function receives:
+
+- `controlProps`: the generated native ID, accessible label, label relationship, hint, disabled state, and accessibility state to spread onto the control;
+- `invalid`: whether the field currently has an error;
+- `required`: the field's required state for custom visual treatment.
+
+`FormField` renders validation feedback once outside the custom control. Use `invalid` only to map the field state into a control's own visual API; do not render the error a second time inside the control.
+
+The required marker is both visible and included in the accessible label. Errors are announced as a polite live region and included in the control's accessibility hint. An explicit `nativeID` can be provided when stable IDs are required; otherwise, `FormField` generates one with React `useId`.

package/dist/components/form-field.d.mts

@@ -0,0 +1,9 @@
+import * as react from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { FormFieldProps } from '../types/form-field.types.mjs';
+import 'react-native';
+import '@impulse-ui-native/primitives';
+
+declare const FormField: react.MemoExoticComponent<({ children, description, disabled, error, label, nativeID, required, style, ...props }: FormFieldProps) => react_jsx_runtime.JSX.Element>;
+
+export { FormField };

package/dist/components/form-field.js

@@ -0,0 +1,76 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { memo, useId, useMemo } from "react";
+import { Control, Typography } from "@impulse-ui-native/primitives";
+import { useThemedStyles } from "@impulse-ui-native/theme";
+import { formFieldStyles } from "./form-field.styles";
+const FormField = memo(function FormField2({
+  children,
+  description,
+  disabled = false,
+  error,
+  label,
+  nativeID,
+  required = false,
+  style,
+  ...props
+}) {
+  const generatedId = useId();
+  const fieldId = nativeID ?? `form-field-${generatedId}`;
+  const labelId = `${fieldId}-label`;
+  const controlId = `${fieldId}-control`;
+  const descriptionId = `${fieldId}-description`;
+  const errorId = `${fieldId}-error`;
+  const invalid = Boolean(error);
+  const accessibleLabel = required ? `${label}, required` : label;
+  const accessibilityHint = [error, description].filter(Boolean).join(" ");
+  const styles = useThemedStyles(formFieldStyles, { disabled }, [disabled]);
+  const controlProps = useMemo(
+    () => ({
+      accessibilityHint: accessibilityHint || void 0,
+      accessibilityLabel: accessibleLabel,
+      accessibilityLabelledBy: labelId,
+      accessibilityState: { disabled },
+      disabled,
+      nativeID: controlId
+    }),
+    [accessibilityHint, accessibleLabel, controlId, disabled, labelId]
+  );
+  const renderProps = useMemo(
+    () => ({ controlProps, invalid, required }),
+    [controlProps, invalid, required]
+  );
+  return /* @__PURE__ */ jsx(
+    Control.Provider,
+    {
+      disabled,
+      error,
+      size: "medium",
+      variant: "outlined",
+      children: /* @__PURE__ */ jsxs(Control.Root, { ...props, nativeID: fieldId, style, children: [
+        /* @__PURE__ */ jsx(
+          Control.Label,
+          {
+            accessibilityLabel: accessibleLabel,
+            disabled,
+            nativeID: labelId,
+            children: required ? `${label} *` : label
+          }
+        ),
+        description ? /* @__PURE__ */ jsx(
+          Typography.Caption,
+          {
+            nativeID: descriptionId,
+            style: styles.description,
+            children: description
+          }
+        ) : null,
+        children(renderProps),
+        /* @__PURE__ */ jsx(Control.Error, { accessibilityLiveRegion: "polite", nativeID: errorId })
+      ] })
+    }
+  );
+});
+export {
+  FormField
+};
+//# sourceMappingURL=form-field.js.map

package/dist/components/form-field.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/form-field.tsx"],"sourcesContent":["import { memo, useId, useMemo } from \"react\";\n\nimport { Control, Typography } from \"@impulse-ui-native/primitives\";\nimport { useThemedStyles } from \"@impulse-ui-native/theme\";\n\nimport type {\n  FormFieldControlProps,\n  FormFieldProps,\n  FormFieldRenderProps,\n} from \"../types\";\nimport { formFieldStyles } from \"./form-field.styles\";\n\nexport const FormField = memo(function FormField({\n  children,\n  description,\n  disabled = false,\n  error,\n  label,\n  nativeID,\n  required = false,\n  style,\n  ...props\n}: FormFieldProps) {\n  const generatedId = useId();\n  const fieldId = nativeID ?? `form-field-${generatedId}`;\n  const labelId = `${fieldId}-label`;\n  const controlId = `${fieldId}-control`;\n  const descriptionId = `${fieldId}-description`;\n  const errorId = `${fieldId}-error`;\n  const invalid = Boolean(error);\n  const accessibleLabel = required ? `${label}, required` : label;\n  const accessibilityHint = [error, description].filter(Boolean).join(\" \");\n  const styles = useThemedStyles(formFieldStyles, { disabled }, [disabled]);\n\n  const controlProps = useMemo<FormFieldControlProps>(\n    () => ({\n      accessibilityHint: accessibilityHint || undefined,\n      accessibilityLabel: accessibleLabel,\n      accessibilityLabelledBy: labelId,\n      accessibilityState: { disabled },\n      disabled,\n      nativeID: controlId,\n    }),\n    [accessibilityHint, accessibleLabel, controlId, disabled, labelId],\n  );\n  const renderProps = useMemo<FormFieldRenderProps>(\n    () => ({ controlProps, invalid, required }),\n    [controlProps, invalid, required],\n  );\n\n  return (\n    <Control.Provider\n      disabled={disabled}\n      error={error}\n      size=\"medium\"\n      variant=\"outlined\"\n    >\n      <Control.Root {...props} nativeID={fieldId} style={style}>\n        <Control.Label\n          accessibilityLabel={accessibleLabel}\n          disabled={disabled}\n          nativeID={labelId}\n        >\n          {required ? `${label} *` : label}\n        </Control.Label>\n        {description ? (\n          <Typography.Caption\n            nativeID={descriptionId}\n            style={styles.description}\n          >\n            {description}\n          </Typography.Caption>\n        ) : null}\n        {children(renderProps)}\n        <Control.Error accessibilityLiveRegion=\"polite\" nativeID={errorId} />\n      </Control.Root>\n    </Control.Provider>\n  );\n});\n"],"mappings":"AAyDM,SACE,KADF;AAzDN,SAAS,MAAM,OAAO,eAAe;AAErC,SAAS,SAAS,kBAAkB;AACpC,SAAS,uBAAuB;AAOhC,SAAS,uBAAuB;AAEzB,MAAM,YAAY,KAAK,SAASA,WAAU;AAAA,EAC/C;AAAA,EACA;AAAA,EACA,WAAW;AAAA,EACX;AAAA,EACA;AAAA,EACA;AAAA,EACA,WAAW;AAAA,EACX;AAAA,EACA,GAAG;AACL,GAAmB;AACjB,QAAM,cAAc,MAAM;AAC1B,QAAM,UAAU,YAAY,cAAc,WAAW;AACrD,QAAM,UAAU,GAAG,OAAO;AAC1B,QAAM,YAAY,GAAG,OAAO;AAC5B,QAAM,gBAAgB,GAAG,OAAO;AAChC,QAAM,UAAU,GAAG,OAAO;AAC1B,QAAM,UAAU,QAAQ,KAAK;AAC7B,QAAM,kBAAkB,WAAW,GAAG,KAAK,eAAe;AAC1D,QAAM,oBAAoB,CAAC,OAAO,WAAW,EAAE,OAAO,OAAO,EAAE,KAAK,GAAG;AACvE,QAAM,SAAS,gBAAgB,iBAAiB,EAAE,SAAS,GAAG,CAAC,QAAQ,CAAC;AAExE,QAAM,eAAe;AAAA,IACnB,OAAO;AAAA,MACL,mBAAmB,qBAAqB;AAAA,MACxC,oBAAoB;AAAA,MACpB,yBAAyB;AAAA,MACzB,oBAAoB,EAAE,SAAS;AAAA,MAC/B;AAAA,MACA,UAAU;AAAA,IACZ;AAAA,IACA,CAAC,mBAAmB,iBAAiB,WAAW,UAAU,OAAO;AAAA,EACnE;AACA,QAAM,cAAc;AAAA,IAClB,OAAO,EAAE,cAAc,SAAS,SAAS;AAAA,IACzC,CAAC,cAAc,SAAS,QAAQ;AAAA,EAClC;AAEA,SACE;AAAA,IAAC,QAAQ;AAAA,IAAR;AAAA,MACC;AAAA,MACA;AAAA,MACA,MAAK;AAAA,MACL,SAAQ;AAAA,MAER,+BAAC,QAAQ,MAAR,EAAc,GAAG,OAAO,UAAU,SAAS,OAC1C;AAAA;AAAA,UAAC,QAAQ;AAAA,UAAR;AAAA,YACC,oBAAoB;AAAA,YACpB;AAAA,YACA,UAAU;AAAA,YAET,qBAAW,GAAG,KAAK,OAAO;AAAA;AAAA,QAC7B;AAAA,QACC,cACC;AAAA,UAAC,WAAW;AAAA,UAAX;AAAA,YACC,UAAU;AAAA,YACV,OAAO,OAAO;AAAA,YAEb;AAAA;AAAA,QACH,IACE;AAAA,QACH,SAAS,WAAW;AAAA,QACrB,oBAAC,QAAQ,OAAR,EAAc,yBAAwB,UAAS,UAAU,SAAS;AAAA,SACrE;AAAA;AAAA,EACF;AAEJ,CAAC;","names":["FormField"]}

package/dist/components/form-field.styles.d.mts

@@ -0,0 +1,12 @@
+import { AppTheme } from '@impulse-ui-native/theme';
+
+declare function formFieldStyles(theme: AppTheme, { disabled }: {
+    disabled: boolean;
+}): {
+    description: {
+        color: string;
+        marginBottom: number;
+    };
+};
+
+export { formFieldStyles };

package/dist/components/form-field.styles.js

@@ -0,0 +1,13 @@
+import { StyleSheet } from "react-native";
+function formFieldStyles(theme, { disabled }) {
+  return StyleSheet.create({
+    description: {
+      color: disabled ? theme.colors.text.disabled : theme.colors.text.secondary,
+      marginBottom: theme.space.xxs
+    }
+  });
+}
+export {
+  formFieldStyles
+};
+//# sourceMappingURL=form-field.styles.js.map

package/dist/components/form-field.styles.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/form-field.styles.ts"],"sourcesContent":["import { StyleSheet } from \"react-native\";\n\nimport type { AppTheme } from \"@impulse-ui-native/theme\";\n\nexport function formFieldStyles(\n  theme: AppTheme,\n  { disabled }: { disabled: boolean },\n) {\n  return StyleSheet.create({\n    description: {\n      color: disabled\n        ? theme.colors.text.disabled\n        : theme.colors.text.secondary,\n      marginBottom: theme.space.xxs,\n    },\n  });\n}\n"],"mappings":"AAAA,SAAS,kBAAkB;AAIpB,SAAS,gBACd,OACA,EAAE,SAAS,GACX;AACA,SAAO,WAAW,OAAO;AAAA,IACvB,aAAa;AAAA,MACX,OAAO,WACH,MAAM,OAAO,KAAK,WAClB,MAAM,OAAO,KAAK;AAAA,MACtB,cAAc,MAAM,MAAM;AAAA,IAC5B;AAAA,EACF,CAAC;AACH;","names":[]}

package/dist/components/index.d.mts

@@ -0,0 +1,6 @@
+export { FormField } from './form-field.mjs';
+import 'react';
+import 'react/jsx-runtime';
+import '../types/form-field.types.mjs';
+import 'react-native';
+import '@impulse-ui-native/primitives';

package/dist/components/index.js

@@ -0,0 +1,5 @@
+import { FormField } from "./form-field";
+export {
+  FormField
+};
+//# sourceMappingURL=index.js.map

package/dist/components/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/index.ts"],"sourcesContent":["export { FormField } from \"./form-field\";\n"],"mappings":"AAAA,SAAS,iBAAiB;","names":[]}

package/dist/index.d.mts

@@ -0,0 +1,6 @@
+export { FormField } from './components/form-field.mjs';
+export { FormFieldControlProps, FormFieldProps, FormFieldRenderProps } from './types/form-field.types.mjs';
+import 'react';
+import 'react/jsx-runtime';
+import 'react-native';
+import '@impulse-ui-native/primitives';

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./components";
+export * from "./types";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./components\";\nexport * from \"./types\";\n"],"mappings":"AAAA,cAAc;AACd,cAAc;","names":[]}

package/dist/types/form-field.types.d.mts

@@ -0,0 +1,27 @@
+import { ReactNode } from 'react';
+import { AccessibilityState } from 'react-native';
+import { ViewProps } from '@impulse-ui-native/primitives';
+
+interface FormFieldControlProps {
+    accessibilityHint?: string;
+    accessibilityLabel: string;
+    accessibilityLabelledBy: string;
+    accessibilityState: AccessibilityState;
+    disabled: boolean;
+    nativeID: string;
+}
+interface FormFieldRenderProps {
+    controlProps: FormFieldControlProps;
+    invalid: boolean;
+    required: boolean;
+}
+interface FormFieldProps extends Omit<ViewProps, "children"> {
+    children: (props: FormFieldRenderProps) => ReactNode;
+    description?: string;
+    disabled?: boolean;
+    error?: string;
+    label: string;
+    required?: boolean;
+}
+
+export type { FormFieldControlProps, FormFieldProps, FormFieldRenderProps };

package/dist/types/form-field.types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=form-field.types.js.map

package/dist/types/form-field.types.js.map

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

package/dist/types/index.d.mts

@@ -0,0 +1,4 @@
+export { FormFieldControlProps, FormFieldProps, FormFieldRenderProps } from './form-field.types.mjs';
+import 'react';
+import 'react-native';
+import '@impulse-ui-native/primitives';

package/dist/types/index.js

@@ -0,0 +1,2 @@
+export * from "./form-field.types";
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/index.ts"],"sourcesContent":["export * from \"./form-field.types\";\n"],"mappings":"AAAA,cAAc;","names":[]}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@impulse-ui-native/form-field",
+  "version": "2.7.0",
+  "description": "Accessible form-field composition for Impulse UI Native controls.",
+  "keywords": [
+    "react-native",
+    "form-field",
+    "accessibility",
+    "validation",
+    "components",
+    "impulse-ui-native"
+  ],
+  "license": "MIT",
+  "source": "src/index.ts",
+  "module": "dist/index.js",
+  "types": "dist/index.d.mts",
+  "react-native": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "react-native": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@impulse-ui-native/theme": "2.7.0",
+    "@impulse-ui-native/primitives": "2.7.0"
+  },
+  "devDependencies": {
+    "@types/react": "~19.2.14",
+    "prettier": "^3.6.2",
+    "react": "19.2.3",
+    "react-native": "0.86.2",
+    "typescript": "~6.0.3",
+    "@impulse-ui-native/prettier-config": "1.0.0",
+    "@impulse-ui-native/tsconfig": "1.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.73"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "prettier": "@impulse-ui-native/prettier-config",
+  "scripts": {
+    "build": "tsup --config tsup.config.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "format": "prettier --write \"./**/*.{ts,tsx,js,jsx,json,md}\" --ignore-path ../../.prettierignore"
+  }
+}