@spark-web/field 0.0.0-snapshot-release-20260409001813

package/CLAUDE.md

@@ -0,0 +1,80 @@
+# @spark-web/field — AI Context
+
+## What this is
+
+The form field wrapper. `Field` provides the label, optional description,
+optional validation message, and the accessibility wiring (aria-describedby,
+aria-invalid, id) that connects a label to its input. Every `TextInput`,
+`Select`, and other form input **must** be wrapped in a `Field`.
+
+## What this is NOT
+
+- Not the input itself — `Field` only provides the label and context; the input
+  (`TextInput`, `Select`, etc.) is the `children`
+- Not a layout component — use `Stack` or `Columns` to arrange multiple `Field`
+  components
+
+## Props interface
+
+| Prop              | Type                                       | Default     | Notes                                                                                   |
+| ----------------- | ------------------------------------------ | ----------- | --------------------------------------------------------------------------------------- |
+| `label`           | `string`                                   | required    | Always required — used for accessibility even if hidden                                 |
+| `labelVisibility` | `'visible' \| 'hidden' \| 'reserve-space'` | `'visible'` | `'hidden'` hides visually but keeps accessible; `'reserve-space'` reserves layout space |
+| `description`     | `string \| ReactNode`                      | —           | Hint text rendered below the label                                                      |
+| `message`         | `string`                                   | —           | Validation message; tone controls its appearance                                        |
+| `tone`            | `'neutral' \| 'critical' \| 'positive'`    | `'neutral'` | `'critical'` marks the input invalid                                                    |
+| `secondaryLabel`  | `string`                                   | —           | Supplementary label text (e.g. "Optional")                                              |
+| `disabled`        | `boolean`                                  | `false`     | Disables the child input via context                                                    |
+| `readOnly`        | `boolean`                                  | `false`     | Makes the child input read-only via context                                             |
+| `adornment`       | `ReactElement`                             | —           | Utility element placed inline with the label (e.g. tooltip)                             |
+| `data`            | `DataAttributeMap`                         | —           | Test/analytics attributes                                                               |
+
+## Common patterns
+
+### Standard labeled input
+
+```tsx
+<Field label="Email address">
+  <TextInput type="email" placeholder="you@example.com" />
+</Field>
+```
+
+### Hidden label (filter context)
+
+Use `labelVisibility="hidden"` when the placeholder or surrounding context makes
+the label redundant visually, but the label is still required for a11y:
+
+```tsx
+<Field label="Search users" labelVisibility="hidden">
+  <TextInput placeholder="Search users">
+    <InputAdornment placement="start">
+      <SearchIcon size="xsmall" tone="placeholder" />
+    </InputAdornment>
+  </TextInput>
+</Field>
+```
+
+### Validation state
+
+```tsx
+<Field label="Password" tone="critical" message="Password is required">
+  <TextInput type="password" />
+</Field>
+```
+
+### Optional field
+
+```tsx
+<Field label="Phone number" secondaryLabel="Optional">
+  <TextInput type="tel" />
+</Field>
+```
+
+## Do NOTs
+
+- NEVER use `TextInput` or `Select` without wrapping them in `Field`
+- NEVER omit `label` — it is always required for accessibility, even with
+  `labelVisibility="hidden"`
+- NEVER pass `id` to the input directly — `Field` manages the id via context
+- NEVER use `tone="critical"` without also providing `message` — the tone alone
+  does not communicate the error to the user

package/README.md

@@ -0,0 +1,132 @@
+---
+title: Field
+isExperimentalPackage: false
+---
+
+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
+
+<PropsTable displayName="Field" />
+
+[data-attribute-map]:
+  https://github.com/brighte-labs/spark-web/blob/e7f6f4285b4cfd876312cc89fbdd094039aa239a/packages/utils/src/internal/buildDataAttributes.ts#L1

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

@@ -0,0 +1,15 @@
+export type FieldState = {
+    disabled: boolean;
+    invalid: boolean;
+    readOnly?: boolean;
+};
+export type InputPropsDerivedFromField = {
+    'aria-describedby'?: string;
+    'aria-invalid': true | undefined;
+    id: string;
+};
+export type FieldContextType = [FieldState, InputPropsDerivedFromField];
+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/field.d.ts

@@ -0,0 +1,53 @@
+import type { DataAttributeMap } from '@spark-web/utils/internal';
+import type { ReactElement, ReactNode } from 'react';
+export type Tone = keyof typeof messageToneMap;
+export type FieldProps = {
+    /** Sets a unique identifier for the component. */
+    id?: string;
+    /** Sets data attributes on the component. */
+    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 | ReactNode;
+    /** 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;
+    /** Sets input to readonly, which is focusable. */
+    readOnly?: boolean;
+};
+/**
+ * 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";
+};
+type FieldMessageProps = Required<Pick<FieldProps, 'message' | 'id' | 'tone'>>;
+export declare const FieldMessage: ({ message, id, tone }: FieldMessageProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,4 @@
+export { FieldContextProvider, useFieldContext } from "./context.js";
+export { Field, FieldMessage, useFieldIds } from "./field.js";
+export type { FieldContextType, FieldState, InputPropsDerivedFromField, } from "./context.js";
+export type { FieldProps, Tone } from "./field.js";

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

@@ -0,0 +1,2 @@
+export * from "./declarations/src/index.js";
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3Bhcmstd2ViLWZpZWxkLmNqcy5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi9kZWNsYXJhdGlvbnMvc3JjL2luZGV4LmQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEifQ==

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

@@ -0,0 +1,212 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var react = require('react');
+var react$1 = require('@emotion/react');
+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 jsxRuntime = require('@emotion/react/jsx-runtime');
+
+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;
+}
+
+/**
+ * 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,
+    _ref$readOnly = _ref.readOnly,
+    readOnly = _ref$readOnly === void 0 ? false : _ref$readOnly;
+  var _useFieldIds = useFieldIds(idProp),
+    descriptionId = _useFieldIds.descriptionId,
+    inputId = _useFieldIds.inputId,
+    messageId = _useFieldIds.messageId;
+
+  // field context
+  var invalid = Boolean(message && tone === 'critical');
+  var fieldContext = react.useMemo(function () {
+    return [{
+      disabled: disabled,
+      invalid: invalid,
+      readOnly: readOnly
+    }, {
+      'aria-describedby': a11y.mergeIds(message && messageId, description ? descriptionId : undefined),
+      'aria-invalid': invalid || undefined,
+      id: inputId
+    }];
+  }, [description, descriptionId, disabled, inputId, invalid, message, messageId, readOnly]);
+
+  // label prep
+  var hiddenLabel = jsxRuntime.jsxs(a11y.VisuallyHidden, {
+    as: "label",
+    htmlFor: inputId,
+    children: [label, " ", secondaryLabel]
+  });
+  var labelElement = {
+    hidden: hiddenLabel,
+    visible: jsxRuntime.jsx(box.Box, {
+      as: "label",
+      htmlFor: inputId,
+      children: jsxRuntime.jsxs(text.Text, {
+        tone: disabled || readOnly ? 'field' : 'neutral',
+        weight: "semibold",
+        children: [label, ' ', secondaryLabel && jsxRuntime.jsx(text.Text, {
+          inline: true,
+          tone: disabled || readOnly ? 'field' : 'muted',
+          weight: "regular",
+          children: secondaryLabel
+        })]
+      })
+    }),
+    'reserve-space': jsxRuntime.jsxs(react.Fragment, {
+      children: [hiddenLabel, jsxRuntime.jsx(text.Text, {
+        "aria-hidden": true,
+        children: "\xA0"
+      })]
+    })
+  };
+  var LabelWrapper = labelVisibility === 'hidden' ? react.Fragment : FieldLabelWrapper;
+  return jsxRuntime.jsx(FieldContextProvider, {
+    value: fieldContext,
+    children: jsxRuntime.jsxs(stack.Stack, {
+      ref: forwardedRef,
+      data: data,
+      gap: "medium",
+      children: [jsxRuntime.jsxs(LabelWrapper, {
+        children: [labelElement[labelVisibility], adornment]
+      }), description && (typeof description === 'string' ? jsxRuntime.jsx(text.Text, {
+        tone: "muted",
+        size: "small",
+        id: descriptionId,
+        children: description
+      }) : jsxRuntime.jsx(box.Box, {
+        as: "label",
+        htmlFor: descriptionId,
+        children: description
+      })), children, message && jsxRuntime.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
+// ------------------------------
+function FieldLabelWrapper(_ref2) {
+  var children = _ref2.children;
+  return jsxRuntime.jsx(box.Box, {
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "spaceBetween",
+    gap: "large",
+    children: children
+  });
+}
+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(_ref3) {
+  var message = _ref3.message,
+    id = _ref3.id,
+    tone = _ref3.tone;
+  var textTone = messageToneMap[tone];
+  var Icon = messageIconMap[tone];
+  return jsxRuntime.jsxs(box.Box, {
+    display: "flex",
+    gap: "xsmall",
+    children: [Icon ? jsxRuntime.jsx(IndicatorContainer, {
+      children: jsxRuntime.jsx(Icon, {
+        size: "xxsmall",
+        tone: tone
+      })
+    }) : null, jsxRuntime.jsx(text.Text, {
+      tone: textTone,
+      size: "small",
+      id: id,
+      children: message
+    })]
+  });
+};
+function IndicatorContainer(_ref4) {
+  var children = _ref4.children;
+  var theme$1 = theme.useTheme();
+  var _theme$typography$tex = theme$1.typography.text.small,
+    mobile = _theme$typography$tex.mobile,
+    tablet = _theme$typography$tex.tablet;
+  var responsiveStyles = theme$1.utils.responsiveStyles({
+    mobile: {
+      height: mobile.capHeight
+    },
+    tablet: {
+      height: tablet.capHeight
+    }
+  });
+  return jsxRuntime.jsx(box.Box, {
+    display: "flex",
+    alignItems: "center",
+    "aria-hidden": true,
+    cursor: "default",
+    flexShrink: 0,
+    css: react$1.css(responsiveStyles),
+    children: children
+  });
+}
+
+exports.Field = Field;
+exports.FieldContextProvider = FieldContextProvider;
+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");
+}