@spark-web/field 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# @spark-web/field
+
+## 1.0.0
+
+### Major Changes
+
+- [#27](https://github.com/brighte-labs/spark-web/pull/27)
+  [`4c8e398`](https://github.com/brighte-labs/spark-web/commit/4c8e3988f8a59d3dab60a6b67b1128b6ff2a5f2c)
+  Thanks [@JedWatson](https://github.com/JedWatson)! - Initial Version
+
+### Patch Changes
+
+- Updated dependencies
+  [[`4c8e398`](https://github.com/brighte-labs/spark-web/commit/4c8e3988f8a59d3dab60a6b67b1128b6ff2a5f2c)]:
+  - @spark-web/a11y@1.0.0
+  - @spark-web/box@1.0.0
+  - @spark-web/icon@1.0.0
+  - @spark-web/stack@1.0.0
+  - @spark-web/text@1.0.0
+  - @spark-web/theme@1.0.0
+  - @spark-web/utils@1.0.0

package/README.md

@@ -0,0 +1,143 @@
+---
+title: Field
+---
+
+Using context, the field component connects the label, description, and message
+to the input element.
+
+```jsx live
+<Field label="Label">
+  <TextInput />
+</Field>
+```
+
+## Example
+
+### Label
+
+Each field must be accompanied by a label. Effective form labeling helps users
+understand what information to enter into an input.
+
+Using placeholder text in lieu of a label is sometimes employed as a
+space-saving method. However, this is not recommended because it hides context
+and presents accessibility issues.
+
+```jsx live
+<Field label="Name">
+  <TextInput />
+</Field>
+```
+
+#### Label visibility
+
+The label must always be provided for assistive technology, but you may hide it
+from sighted users when the intent can be inferred from context.
+
+```jsx live
+<Stack gap="xlarge">
+  <Field label="Name" labelVisibility="hidden">
+    <TextInput placeholder="hidden" />
+  </Field>
+  <Columns gap="small">
+    <Field label="Name">
+      <TextInput placeholder="visible" />
+    </Field>
+    <Field label="Name" labelVisibility="reserve-space">
+      <TextInput placeholder="reserve-space" />
+    </Field>
+  </Columns>
+</Stack>
+```
+
+#### Secondary label
+
+Provide additional context, typically used to indicate that the field is
+optional.
+
+```jsx live
+<Field label="Name" secondaryLabel="(Optional)">
+  <TextInput />
+</Field>
+```
+
+### Adornment
+
+Optionally provide a utility or contextual hint, related to the field.
+
+```jsx live
+<Field
+  label="Username"
+  adornment={
+    <Text>
+      <TextLink href="#">Forgot username?</TextLink>
+    </Text>
+  }
+>
+  <TextInput />
+</Field>
+```
+
+### Description
+
+Provides pertinent information that assists the user in completing a field.
+Description text is always visible and appears underneath the label. Use
+sentence-style capitalisation, and in most cases, write the text as full
+sentences with punctuation.
+
+```jsx live
+<Field
+  label="Email"
+  description="We take your privacy seriously. We will never give your email to a third party."
+>
+  <TextInput type="email" />
+</Field>
+```
+
+### Message and tone
+
+The “message” is used to communicate the status of a field, such as an error
+message. This will be announced on focus and can be combined with a “tone” to
+illustrate intent.
+
+```jsx live
+<Stack gap="xlarge">
+  <Field label="Label" tone="critical" message="Critical message">
+    <TextInput />
+  </Field>
+  <Field label="Label" tone="positive" message="Positive message">
+    <TextInput />
+  </Field>
+  <Field label="Label" tone="neutral" message="Neutral message">
+    <TextInput />
+  </Field>
+</Stack>
+```
+
+### Disabled
+
+Mark the field as disabled by passing true to the disabled prop.
+
+```jsx live
+<Field label="Label" secondaryLabel="Secondary label" disabled>
+  <TextInput value="Text in disabled field" />
+</Field>
+```
+
+## Props
+
+| Prop             | Type                                     | Default   | Description                                                                                                                                      |
+| ---------------- | ---------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| id?              | string                                   |           | Sets a unique identifier for the component.                                                                                                      |
+| data?            | [DataAttributeMap][data-attribute-map]   |           | Sets data attributes on the component.                                                                                                           |
+| adornment?       | React.ReactElement                       |           | Optionally provide a utility or contextual hint, related to the field.                                                                           |
+| children         | React.ReactNode                          |           | Children elements to be rendered within the component. Expected to be Input elements.                                                            |
+| disabled?        | boolean                                  |           | Indicates that the field is perceivable but disabled, so it is not editable or otherwise operable.                                               |
+| description?     | string                                   |           | Sets a description for the field to provide additional information that will aid user input.                                                     |
+| label            | string                                   |           | Sets a label for the field.                                                                                                                      |
+| labelVisibility? | 'hidden' \| 'reserve-space' \| 'visible' | 'visible' | The label must always be provided for assistive technology, but you may hide it from sighted users when the intent can be inferred from context. |
+| message?         | string                                   |           | Provide a message, informing the user about changes in state.                                                                                    |
+| secondaryLabel?  | string                                   |           | Provides additional context, typically used to indicate that the field is optional.                                                              |
+| tone?            | 'critical' \| 'neutral' \| 'positive'    | 'neutral' | Provide a tone to influence elements of the field, and its input.                                                                                |
+
+[data-attribute-map]:
+  https://bitbucket.org/brighte-energy/energy/src/14a694872cc43bb454981bada65f5f12b56f77c9/spark-web/packages/utils-spark/src/buildDataAttributes.ts#spark-web/packages/utils-spark/src/buildDataAttributes.ts-1

package/dist/declarations/src/Field.d.ts

@@ -0,0 +1,49 @@
+import type { DataAttributeMap } from '@spark-web/utils/internal';
+import type { ReactElement, ReactNode } from 'react';
+export declare type Tone = keyof typeof messageToneMap;
+export declare type FieldProps = {
+    id?: string;
+    data?: DataAttributeMap;
+    /** Optionally provide a utility or contextual hint, related to the field. */
+    adornment?: ReactElement;
+    /** Input component  */
+    children: ReactNode;
+    /**
+     * Indicates that the field is perceivable but disabled, so it is not editable
+     * or otherwise operable.
+     */
+    disabled?: boolean;
+    /** Provide additional information that will aid user input. */
+    description?: string;
+    /** Concisely label the field. */
+    label: string;
+    /**
+     * The label must always be provided for assistive technology, but you may
+     * hide it from sighted users when the intent can be inferred from context.
+     */
+    labelVisibility?: 'hidden' | 'reserve-space' | 'visible';
+    /** Provide a message, informing the user about changes in state. */
+    message?: string;
+    /** Additional context, typically used to indicate that the field is optional. */
+    secondaryLabel?: string;
+    /** Provide a tone to influence elements of the field, and its input. */
+    tone?: Tone;
+};
+/**
+ * Using a [context](https://reactjs.org/docs/context.html), the field
+ * component connects the label, description, and message to the input element.
+ */
+export declare const Field: import("react").ForwardRefExoticComponent<FieldProps & import("react").RefAttributes<HTMLDivElement>>;
+export declare function useFieldIds(id?: string): {
+    descriptionId: string;
+    inputId: string;
+    messageId: string;
+};
+declare const messageToneMap: {
+    readonly critical: "critical";
+    readonly neutral: "muted";
+    readonly positive: "positive";
+};
+declare type FieldMessageProps = Required<Pick<FieldProps, 'message' | 'id' | 'tone'>>;
+export declare const FieldMessage: ({ message, id, tone }: FieldMessageProps) => JSX.Element;
+export {};

package/dist/declarations/src/context.d.ts

@@ -0,0 +1,11 @@
+/// <reference types="react" />
+export declare type FieldContextType = {
+    'aria-describedby'?: string;
+    id: string;
+    disabled: boolean;
+    invalid: boolean;
+};
+export declare const FieldContext: import("react").Context<FieldContextType | null>;
+export declare const FieldContextProvider: import("react").Provider<FieldContextType | null>;
+export declare const FIELD_CONTEXT_ERROR_MESSAGE = "Input components must be inside a `Field`.";
+export declare function useFieldContext(): FieldContextType;

package/dist/declarations/src/index.d.ts

@@ -0,0 +1,4 @@
+export { useFieldContext } from './context';
+export { Field, FieldMessage, useFieldIds } from './Field';
+export type { FieldContextType } from './context';
+export type { FieldProps, Tone } from './Field';

package/dist/spark-web-field.cjs.d.ts

@@ -0,0 +1 @@
+export * from "./declarations/src/index";

package/dist/spark-web-field.cjs.dev.js

@@ -0,0 +1,190 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var React = require('react');
+var _objectWithoutProperties = require('@babel/runtime/helpers/esm/objectWithoutProperties');
+var _extends = require('@babel/runtime/helpers/esm/extends');
+var css = require('@emotion/css');
+var a11y = require('@spark-web/a11y');
+var box = require('@spark-web/box');
+var icon = require('@spark-web/icon');
+var stack = require('@spark-web/stack');
+var text = require('@spark-web/text');
+var theme = require('@spark-web/theme');
+var internal = require('@spark-web/utils/internal');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { 'default': e }; }
+
+var React__default = /*#__PURE__*/_interopDefault(React);
+
+var FieldContext = /*#__PURE__*/React.createContext(null);
+var FieldContextProvider = FieldContext.Provider;
+var FIELD_CONTEXT_ERROR_MESSAGE = 'Input components must be inside a `Field`.';
+function useFieldContext() {
+  var ctx = React.useContext(FieldContext);
+
+  if (!ctx) {
+    throw new Error(FIELD_CONTEXT_ERROR_MESSAGE);
+  }
+
+  return ctx;
+}
+
+var _excluded = ["children"];
+var __jsx = React__default["default"].createElement;
+
+/**
+ * Using a [context](https://reactjs.org/docs/context.html), the field
+ * component connects the label, description, and message to the input element.
+ */
+var Field = /*#__PURE__*/React.forwardRef(function (_ref, forwardedRef) {
+  var children = _ref.children,
+      idProp = _ref.id,
+      data = _ref.data,
+      description = _ref.description,
+      _ref$disabled = _ref.disabled,
+      disabled = _ref$disabled === void 0 ? false : _ref$disabled,
+      label = _ref.label,
+      adornment = _ref.adornment,
+      _ref$labelVisibility = _ref.labelVisibility,
+      labelVisibility = _ref$labelVisibility === void 0 ? 'visible' : _ref$labelVisibility,
+      message = _ref.message,
+      secondaryLabel = _ref.secondaryLabel,
+      _ref$tone = _ref.tone,
+      tone = _ref$tone === void 0 ? 'neutral' : _ref$tone;
+
+  var _useFieldIds = useFieldIds(idProp),
+      descriptionId = _useFieldIds.descriptionId,
+      inputId = _useFieldIds.inputId,
+      messageId = _useFieldIds.messageId; // field context
+
+
+  var fieldContext = {
+    'aria-describedby': a11y.mergeIds(message && messageId, description && descriptionId),
+    id: inputId,
+    disabled: disabled,
+    invalid: Boolean(message && tone === 'critical')
+  }; // label prep
+
+  var hiddenLabel = __jsx(a11y.VisuallyHidden, {
+    as: "label",
+    htmlFor: inputId
+  }, label, " ", secondaryLabel);
+
+  var labelElement = {
+    hidden: hiddenLabel,
+    visible: __jsx(box.Box, {
+      as: "label",
+      htmlFor: inputId
+    }, __jsx(text.Text, {
+      inline: true,
+      tone: disabled ? 'disabled' : 'neutral',
+      weight: "strong"
+    }, label, ' ', secondaryLabel && __jsx(text.Text, {
+      inline: true,
+      tone: disabled ? 'disabled' : 'muted'
+    }, secondaryLabel))),
+    'reserve-space': __jsx(React.Fragment, null, hiddenLabel, __jsx(text.Text, {
+      inline: true,
+      "aria-hidden": true
+    }, "\xA0"))
+  };
+  return __jsx(FieldContextProvider, {
+    value: fieldContext
+  }, __jsx(stack.Stack, _extends({
+    gap: labelVisibility === 'hidden' ? undefined : 'small',
+    ref: forwardedRef
+  }, data ? internal.buildDataAttributes(data) : null), __jsx(box.Box, {
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "spaceBetween",
+    gap: "large"
+  }, labelElement[labelVisibility], adornment), description && __jsx(text.Text, {
+    tone: "muted",
+    size: "small",
+    id: descriptionId
+  }, description), children, message && __jsx(FieldMessage, {
+    tone: tone,
+    id: messageId,
+    message: message
+  })));
+});
+Field.displayName = 'Field'; // Utils
+// ------------------------------
+
+function useFieldIds(id) {
+  var inputId = a11y.useId(id);
+  var descriptionId = a11y.composeId(inputId, 'description');
+  var messageId = a11y.composeId(inputId, 'message');
+  return {
+    descriptionId: descriptionId,
+    inputId: inputId,
+    messageId: messageId
+  };
+} // Styled components
+// ------------------------------
+
+var messageToneMap = {
+  critical: 'critical',
+  neutral: 'muted',
+  positive: 'positive'
+}; // NOTE: use icons in addition to color for folks with visions issues
+
+var messageIconMap = {
+  critical: icon.ExclamationCircleIcon,
+  neutral: null,
+  positive: icon.CheckCircleIcon
+};
+var FieldMessage = function FieldMessage(_ref2) {
+  var message = _ref2.message,
+      id = _ref2.id,
+      tone = _ref2.tone;
+  var textTone = messageToneMap[tone];
+  var Icon = messageIconMap[tone];
+  return __jsx(box.Box, {
+    display: "flex",
+    gap: "xsmall"
+  }, Icon ? __jsx(IndicatorContainer, null, __jsx(Icon, {
+    size: "xxsmall",
+    tone: tone
+  })) : null, __jsx(text.Text, {
+    tone: textTone,
+    size: "small",
+    id: id
+  }, message));
+};
+
+function IndicatorContainer(_ref3) {
+  var children = _ref3.children,
+      props = _objectWithoutProperties(_ref3, _excluded);
+
+  var _useTheme = theme.useTheme(),
+      typography = _useTheme.typography,
+      utils = _useTheme.utils;
+
+  var _typography$text$smal = typography.text.small,
+      mobile = _typography$text$smal.mobile,
+      tablet = _typography$text$smal.tablet;
+  var responsiveStyles = utils.responsiveStyles({
+    mobile: {
+      height: mobile.capHeight
+    },
+    tablet: {
+      height: tablet.capHeight
+    }
+  });
+  return __jsx(box.Box, _extends({
+    display: "flex",
+    alignItems: "center",
+    "aria-hidden": true,
+    cursor: "default",
+    flexShrink: 0,
+    className: css.css(responsiveStyles)
+  }, props), children);
+}
+
+exports.Field = Field;
+exports.FieldMessage = FieldMessage;
+exports.useFieldContext = useFieldContext;
+exports.useFieldIds = useFieldIds;

package/dist/spark-web-field.cjs.js

@@ -0,0 +1,7 @@
+'use strict';
+
+if (process.env.NODE_ENV === "production") {
+  module.exports = require("./spark-web-field.cjs.prod.js");
+} else {
+  module.exports = require("./spark-web-field.cjs.dev.js");
+}

package/dist/spark-web-field.cjs.prod.js

@@ -0,0 +1,190 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var React = require('react');
+var _objectWithoutProperties = require('@babel/runtime/helpers/esm/objectWithoutProperties');
+var _extends = require('@babel/runtime/helpers/esm/extends');
+var css = require('@emotion/css');
+var a11y = require('@spark-web/a11y');
+var box = require('@spark-web/box');
+var icon = require('@spark-web/icon');
+var stack = require('@spark-web/stack');
+var text = require('@spark-web/text');
+var theme = require('@spark-web/theme');
+var internal = require('@spark-web/utils/internal');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { 'default': e }; }
+
+var React__default = /*#__PURE__*/_interopDefault(React);
+
+var FieldContext = /*#__PURE__*/React.createContext(null);
+var FieldContextProvider = FieldContext.Provider;
+var FIELD_CONTEXT_ERROR_MESSAGE = 'Input components must be inside a `Field`.';
+function useFieldContext() {
+  var ctx = React.useContext(FieldContext);
+
+  if (!ctx) {
+    throw new Error(FIELD_CONTEXT_ERROR_MESSAGE);
+  }
+
+  return ctx;
+}
+
+var _excluded = ["children"];
+var __jsx = React__default["default"].createElement;
+
+/**
+ * Using a [context](https://reactjs.org/docs/context.html), the field
+ * component connects the label, description, and message to the input element.
+ */
+var Field = /*#__PURE__*/React.forwardRef(function (_ref, forwardedRef) {
+  var children = _ref.children,
+      idProp = _ref.id,
+      data = _ref.data,
+      description = _ref.description,
+      _ref$disabled = _ref.disabled,
+      disabled = _ref$disabled === void 0 ? false : _ref$disabled,
+      label = _ref.label,
+      adornment = _ref.adornment,
+      _ref$labelVisibility = _ref.labelVisibility,
+      labelVisibility = _ref$labelVisibility === void 0 ? 'visible' : _ref$labelVisibility,
+      message = _ref.message,
+      secondaryLabel = _ref.secondaryLabel,
+      _ref$tone = _ref.tone,
+      tone = _ref$tone === void 0 ? 'neutral' : _ref$tone;
+
+  var _useFieldIds = useFieldIds(idProp),
+      descriptionId = _useFieldIds.descriptionId,
+      inputId = _useFieldIds.inputId,
+      messageId = _useFieldIds.messageId; // field context
+
+
+  var fieldContext = {
+    'aria-describedby': a11y.mergeIds(message && messageId, description && descriptionId),
+    id: inputId,
+    disabled: disabled,
+    invalid: Boolean(message && tone === 'critical')
+  }; // label prep
+
+  var hiddenLabel = __jsx(a11y.VisuallyHidden, {
+    as: "label",
+    htmlFor: inputId
+  }, label, " ", secondaryLabel);
+
+  var labelElement = {
+    hidden: hiddenLabel,
+    visible: __jsx(box.Box, {
+      as: "label",
+      htmlFor: inputId
+    }, __jsx(text.Text, {
+      inline: true,
+      tone: disabled ? 'disabled' : 'neutral',
+      weight: "strong"
+    }, label, ' ', secondaryLabel && __jsx(text.Text, {
+      inline: true,
+      tone: disabled ? 'disabled' : 'muted'
+    }, secondaryLabel))),
+    'reserve-space': __jsx(React.Fragment, null, hiddenLabel, __jsx(text.Text, {
+      inline: true,
+      "aria-hidden": true
+    }, "\xA0"))
+  };
+  return __jsx(FieldContextProvider, {
+    value: fieldContext
+  }, __jsx(stack.Stack, _extends({
+    gap: labelVisibility === 'hidden' ? undefined : 'small',
+    ref: forwardedRef
+  }, data ? internal.buildDataAttributes(data) : null), __jsx(box.Box, {
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "spaceBetween",
+    gap: "large"
+  }, labelElement[labelVisibility], adornment), description && __jsx(text.Text, {
+    tone: "muted",
+    size: "small",
+    id: descriptionId
+  }, description), children, message && __jsx(FieldMessage, {
+    tone: tone,
+    id: messageId,
+    message: message
+  })));
+});
+Field.displayName = 'Field'; // Utils
+// ------------------------------
+
+function useFieldIds(id) {
+  var inputId = a11y.useId(id);
+  var descriptionId = a11y.composeId(inputId, 'description');
+  var messageId = a11y.composeId(inputId, 'message');
+  return {
+    descriptionId: descriptionId,
+    inputId: inputId,
+    messageId: messageId
+  };
+} // Styled components
+// ------------------------------
+
+var messageToneMap = {
+  critical: 'critical',
+  neutral: 'muted',
+  positive: 'positive'
+}; // NOTE: use icons in addition to color for folks with visions issues
+
+var messageIconMap = {
+  critical: icon.ExclamationCircleIcon,
+  neutral: null,
+  positive: icon.CheckCircleIcon
+};
+var FieldMessage = function FieldMessage(_ref2) {
+  var message = _ref2.message,
+      id = _ref2.id,
+      tone = _ref2.tone;
+  var textTone = messageToneMap[tone];
+  var Icon = messageIconMap[tone];
+  return __jsx(box.Box, {
+    display: "flex",
+    gap: "xsmall"
+  }, Icon ? __jsx(IndicatorContainer, null, __jsx(Icon, {
+    size: "xxsmall",
+    tone: tone
+  })) : null, __jsx(text.Text, {
+    tone: textTone,
+    size: "small",
+    id: id
+  }, message));
+};
+
+function IndicatorContainer(_ref3) {
+  var children = _ref3.children,
+      props = _objectWithoutProperties(_ref3, _excluded);
+
+  var _useTheme = theme.useTheme(),
+      typography = _useTheme.typography,
+      utils = _useTheme.utils;
+
+  var _typography$text$smal = typography.text.small,
+      mobile = _typography$text$smal.mobile,
+      tablet = _typography$text$smal.tablet;
+  var responsiveStyles = utils.responsiveStyles({
+    mobile: {
+      height: mobile.capHeight
+    },
+    tablet: {
+      height: tablet.capHeight
+    }
+  });
+  return __jsx(box.Box, _extends({
+    display: "flex",
+    alignItems: "center",
+    "aria-hidden": true,
+    cursor: "default",
+    flexShrink: 0,
+    className: css.css(responsiveStyles)
+  }, props), children);
+}
+
+exports.Field = Field;
+exports.FieldMessage = FieldMessage;
+exports.useFieldContext = useFieldContext;
+exports.useFieldIds = useFieldIds;

package/dist/spark-web-field.esm.js

@@ -0,0 +1,179 @@
+import React, { createContext, useContext, forwardRef, Fragment } from 'react';
+import _objectWithoutProperties from '@babel/runtime/helpers/esm/objectWithoutProperties';
+import _extends from '@babel/runtime/helpers/esm/extends';
+import { css } from '@emotion/css';
+import { mergeIds, VisuallyHidden, useId, composeId } from '@spark-web/a11y';
+import { Box } from '@spark-web/box';
+import { ExclamationCircleIcon, CheckCircleIcon } from '@spark-web/icon';
+import { Stack } from '@spark-web/stack';
+import { Text } from '@spark-web/text';
+import { useTheme } from '@spark-web/theme';
+import { buildDataAttributes } from '@spark-web/utils/internal';
+
+var FieldContext = /*#__PURE__*/createContext(null);
+var FieldContextProvider = FieldContext.Provider;
+var FIELD_CONTEXT_ERROR_MESSAGE = 'Input components must be inside a `Field`.';
+function useFieldContext() {
+  var ctx = useContext(FieldContext);
+
+  if (!ctx) {
+    throw new Error(FIELD_CONTEXT_ERROR_MESSAGE);
+  }
+
+  return ctx;
+}
+
+var _excluded = ["children"];
+var __jsx = React.createElement;
+
+/**
+ * Using a [context](https://reactjs.org/docs/context.html), the field
+ * component connects the label, description, and message to the input element.
+ */
+var Field = /*#__PURE__*/forwardRef(function (_ref, forwardedRef) {
+  var children = _ref.children,
+      idProp = _ref.id,
+      data = _ref.data,
+      description = _ref.description,
+      _ref$disabled = _ref.disabled,
+      disabled = _ref$disabled === void 0 ? false : _ref$disabled,
+      label = _ref.label,
+      adornment = _ref.adornment,
+      _ref$labelVisibility = _ref.labelVisibility,
+      labelVisibility = _ref$labelVisibility === void 0 ? 'visible' : _ref$labelVisibility,
+      message = _ref.message,
+      secondaryLabel = _ref.secondaryLabel,
+      _ref$tone = _ref.tone,
+      tone = _ref$tone === void 0 ? 'neutral' : _ref$tone;
+
+  var _useFieldIds = useFieldIds(idProp),
+      descriptionId = _useFieldIds.descriptionId,
+      inputId = _useFieldIds.inputId,
+      messageId = _useFieldIds.messageId; // field context
+
+
+  var fieldContext = {
+    'aria-describedby': mergeIds(message && messageId, description && descriptionId),
+    id: inputId,
+    disabled: disabled,
+    invalid: Boolean(message && tone === 'critical')
+  }; // label prep
+
+  var hiddenLabel = __jsx(VisuallyHidden, {
+    as: "label",
+    htmlFor: inputId
+  }, label, " ", secondaryLabel);
+
+  var labelElement = {
+    hidden: hiddenLabel,
+    visible: __jsx(Box, {
+      as: "label",
+      htmlFor: inputId
+    }, __jsx(Text, {
+      inline: true,
+      tone: disabled ? 'disabled' : 'neutral',
+      weight: "strong"
+    }, label, ' ', secondaryLabel && __jsx(Text, {
+      inline: true,
+      tone: disabled ? 'disabled' : 'muted'
+    }, secondaryLabel))),
+    'reserve-space': __jsx(Fragment, null, hiddenLabel, __jsx(Text, {
+      inline: true,
+      "aria-hidden": true
+    }, "\xA0"))
+  };
+  return __jsx(FieldContextProvider, {
+    value: fieldContext
+  }, __jsx(Stack, _extends({
+    gap: labelVisibility === 'hidden' ? undefined : 'small',
+    ref: forwardedRef
+  }, data ? buildDataAttributes(data) : null), __jsx(Box, {
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "spaceBetween",
+    gap: "large"
+  }, labelElement[labelVisibility], adornment), description && __jsx(Text, {
+    tone: "muted",
+    size: "small",
+    id: descriptionId
+  }, description), children, message && __jsx(FieldMessage, {
+    tone: tone,
+    id: messageId,
+    message: message
+  })));
+});
+Field.displayName = 'Field'; // Utils
+// ------------------------------
+
+function useFieldIds(id) {
+  var inputId = useId(id);
+  var descriptionId = composeId(inputId, 'description');
+  var messageId = composeId(inputId, 'message');
+  return {
+    descriptionId: descriptionId,
+    inputId: inputId,
+    messageId: messageId
+  };
+} // Styled components
+// ------------------------------
+
+var messageToneMap = {
+  critical: 'critical',
+  neutral: 'muted',
+  positive: 'positive'
+}; // NOTE: use icons in addition to color for folks with visions issues
+
+var messageIconMap = {
+  critical: ExclamationCircleIcon,
+  neutral: null,
+  positive: CheckCircleIcon
+};
+var FieldMessage = function FieldMessage(_ref2) {
+  var message = _ref2.message,
+      id = _ref2.id,
+      tone = _ref2.tone;
+  var textTone = messageToneMap[tone];
+  var Icon = messageIconMap[tone];
+  return __jsx(Box, {
+    display: "flex",
+    gap: "xsmall"
+  }, Icon ? __jsx(IndicatorContainer, null, __jsx(Icon, {
+    size: "xxsmall",
+    tone: tone
+  })) : null, __jsx(Text, {
+    tone: textTone,
+    size: "small",
+    id: id
+  }, message));
+};
+
+function IndicatorContainer(_ref3) {
+  var children = _ref3.children,
+      props = _objectWithoutProperties(_ref3, _excluded);
+
+  var _useTheme = useTheme(),
+      typography = _useTheme.typography,
+      utils = _useTheme.utils;
+
+  var _typography$text$smal = typography.text.small,
+      mobile = _typography$text$smal.mobile,
+      tablet = _typography$text$smal.tablet;
+  var responsiveStyles = utils.responsiveStyles({
+    mobile: {
+      height: mobile.capHeight
+    },
+    tablet: {
+      height: tablet.capHeight
+    }
+  });
+  return __jsx(Box, _extends({
+    display: "flex",
+    alignItems: "center",
+    "aria-hidden": true,
+    cursor: "default",
+    flexShrink: 0,
+    className: css(responsiveStyles)
+  }, props), children);
+}
+
+export { Field, FieldMessage, useFieldContext, useFieldIds };

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@spark-web/field",
+  "license": "MIT",
+  "version": "1.0.0",
+  "main": "dist/spark-web-field.cjs.js",
+  "module": "dist/spark-web-field.esm.js",
+  "devDependencies": {
+    "@types/react": "^17.0.12"
+  },
+  "dependencies": {
+    "@babel/runtime": "^7.14.6",
+    "@emotion/css": "^11.7.1",
+    "@spark-web/a11y": "^1.0.0",
+    "@spark-web/box": "^1.0.0",
+    "@spark-web/icon": "^1.0.0",
+    "@spark-web/stack": "^1.0.0",
+    "@spark-web/text": "^1.0.0",
+    "@spark-web/theme": "^1.0.0",
+    "@spark-web/utils": "^1.0.0",
+    "react": "^17.0.2"
+  },
+  "engines": {
+    "node": ">= 14.13"
+  }
+}

package/src/Field.tsx

@@ -0,0 +1,214 @@
+import { css } from '@emotion/css';
+import { composeId, mergeIds, useId, VisuallyHidden } from '@spark-web/a11y';
+import { Box } from '@spark-web/box';
+import { CheckCircleIcon, ExclamationCircleIcon } from '@spark-web/icon';
+import { Stack } from '@spark-web/stack';
+import { Text } from '@spark-web/text';
+import { useTheme } from '@spark-web/theme';
+import type { DataAttributeMap } from '@spark-web/utils/internal';
+import { buildDataAttributes } from '@spark-web/utils/internal';
+import type { ReactElement, ReactNode } from 'react';
+import { forwardRef, Fragment } from 'react';
+
+import { FieldContextProvider } from './context';
+
+export type Tone = keyof typeof messageToneMap;
+
+export type FieldProps = {
+  id?: string;
+  data?: DataAttributeMap;
+
+  /** Optionally provide a utility or contextual hint, related to the field. */
+  adornment?: ReactElement;
+  /** Input component  */
+  children: ReactNode;
+  /**
+   * Indicates that the field is perceivable but disabled, so it is not editable
+   * or otherwise operable.
+   */
+  disabled?: boolean;
+  /** Provide additional information that will aid user input. */
+  description?: string;
+  /** Concisely label the field. */
+  label: string;
+  /**
+   * The label must always be provided for assistive technology, but you may
+   * hide it from sighted users when the intent can be inferred from context.
+   */
+  labelVisibility?: 'hidden' | 'reserve-space' | 'visible';
+  /** Provide a message, informing the user about changes in state. */
+  message?: string;
+  /** Additional context, typically used to indicate that the field is optional. */
+  secondaryLabel?: string;
+  /** Provide a tone to influence elements of the field, and its input. */
+  tone?: Tone;
+};
+
+/**
+ * Using a [context](https://reactjs.org/docs/context.html), the field
+ * component connects the label, description, and message to the input element.
+ */
+export const Field = forwardRef<HTMLDivElement, FieldProps>(
+  (
+    {
+      children,
+      id: idProp,
+      data,
+
+      description,
+      disabled = false,
+      label,
+      adornment,
+      labelVisibility = 'visible',
+      message,
+      secondaryLabel,
+      tone = 'neutral',
+    },
+    forwardedRef
+  ) => {
+    const { descriptionId, inputId, messageId } = useFieldIds(idProp);
+
+    // field context
+    const fieldContext = {
+      'aria-describedby': mergeIds(
+        message && messageId,
+        description && descriptionId
+      ),
+      id: inputId,
+      disabled,
+      invalid: Boolean(message && tone === 'critical'),
+    };
+
+    // label prep
+    const hiddenLabel = (
+      <VisuallyHidden as="label" htmlFor={inputId}>
+        {label} {secondaryLabel}
+      </VisuallyHidden>
+    );
+    const labelElement = {
+      hidden: hiddenLabel,
+      visible: (
+        <Box as="label" htmlFor={inputId}>
+          <Text inline tone={disabled ? 'disabled' : 'neutral'} weight="strong">
+            {label}{' '}
+            {secondaryLabel && (
+              <Text inline tone={disabled ? 'disabled' : 'muted'}>
+                {secondaryLabel}
+              </Text>
+            )}
+          </Text>
+        </Box>
+      ),
+      'reserve-space': (
+        <Fragment>
+          {hiddenLabel}
+          <Text inline aria-hidden>
+            &nbsp;
+          </Text>
+        </Fragment>
+      ),
+    };
+
+    return (
+      <FieldContextProvider value={fieldContext}>
+        <Stack
+          gap={labelVisibility === 'hidden' ? undefined : 'small'}
+          ref={forwardedRef}
+          {...(data ? buildDataAttributes(data) : null)}
+        >
+          <Box
+            display="flex"
+            alignItems="center"
+            justifyContent="spaceBetween"
+            gap="large"
+          >
+            {labelElement[labelVisibility]}
+            {adornment}
+          </Box>
+
+          {description && (
+            <Text tone="muted" size="small" id={descriptionId}>
+              {description}
+            </Text>
+          )}
+
+          {children}
+
+          {message && (
+            <FieldMessage tone={tone} id={messageId} message={message} />
+          )}
+        </Stack>
+      </FieldContextProvider>
+    );
+  }
+);
+Field.displayName = 'Field';
+
+// Utils
+// ------------------------------
+
+export function useFieldIds(id?: string) {
+  const inputId = useId(id);
+  const descriptionId = composeId(inputId, 'description');
+  const messageId = composeId(inputId, 'message');
+
+  return { descriptionId, inputId, messageId };
+}
+
+// Styled components
+// ------------------------------
+
+const messageToneMap = {
+  critical: 'critical',
+  neutral: 'muted',
+  positive: 'positive',
+} as const;
+
+// NOTE: use icons in addition to color for folks with visions issues
+const messageIconMap = {
+  critical: ExclamationCircleIcon,
+  neutral: null,
+  positive: CheckCircleIcon,
+} as const;
+
+type FieldMessageProps = Required<Pick<FieldProps, 'message' | 'id' | 'tone'>>;
+export const FieldMessage = ({ message, id, tone }: FieldMessageProps) => {
+  const textTone = messageToneMap[tone];
+  const Icon = messageIconMap[tone];
+
+  return (
+    <Box display="flex" gap="xsmall">
+      {Icon ? (
+        <IndicatorContainer>
+          <Icon size="xxsmall" tone={tone} />
+        </IndicatorContainer>
+      ) : null}
+      <Text tone={textTone} size="small" id={id}>
+        {message}
+      </Text>
+    </Box>
+  );
+};
+
+function IndicatorContainer({ children, ...props }: { children: ReactNode }) {
+  const { typography, utils } = useTheme();
+  const { mobile, tablet } = typography.text.small;
+  const responsiveStyles = utils.responsiveStyles({
+    mobile: { height: mobile.capHeight },
+    tablet: { height: tablet.capHeight },
+  });
+
+  return (
+    <Box
+      display="flex"
+      alignItems="center"
+      aria-hidden
+      cursor="default"
+      flexShrink={0}
+      className={css(responsiveStyles)}
+      {...props}
+    >
+      {children}
+    </Box>
+  );
+}

package/src/context.ts

@@ -0,0 +1,24 @@
+import { createContext, useContext } from 'react';
+
+export type FieldContextType = {
+  'aria-describedby'?: string;
+  id: string;
+  disabled: boolean;
+  invalid: boolean;
+};
+
+export const FieldContext = createContext<FieldContextType | null>(null);
+export const FieldContextProvider = FieldContext.Provider;
+
+export const FIELD_CONTEXT_ERROR_MESSAGE =
+  'Input components must be inside a `Field`.';
+
+export function useFieldContext() {
+  const ctx = useContext(FieldContext);
+
+  if (!ctx) {
+    throw new Error(FIELD_CONTEXT_ERROR_MESSAGE);
+  }
+
+  return ctx;
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export { useFieldContext } from './context';
+export { Field, FieldMessage, useFieldIds } from './Field';
+
+// types
+
+export type { FieldContextType } from './context';
+export type { FieldProps, Tone } from './Field';