@spark-web/field 5.2.0 → 5.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/CLAUDE.md +80 -0
  3. package/dist/declarations/src/context.d.ts +3 -4
  4. package/dist/declarations/src/field.d.ts +3 -3
  5. package/dist/spark-web-field.cjs.d.ts +1 -1
  6. package/package.json +12 -11
package/CHANGELOG.md CHANGED
@@ -1,5 +1,40 @@
1
1
  # @spark-web/field
2
2
 
3
+ ## 5.3.1
4
+
5
+ ### Patch Changes
6
+
7
+ - [#782](https://github.com/brighte-labs/spark-web/pull/782)
8
+ [`bb41800`](https://github.com/brighte-labs/spark-web/commit/bb418004d21165f72f4bf2456afea844ee04a21c)
9
+ Thanks [@jacobporci-brighte](https://github.com/jacobporci-brighte)! -
10
+ **docs:** add CLAUDE.md AI context files to foundation and form packages;
11
+ patch data-table with manual sort and spinner overlay patterns
12
+ - Updated dependencies
13
+ [[`bb41800`](https://github.com/brighte-labs/spark-web/commit/bb418004d21165f72f4bf2456afea844ee04a21c)]:
14
+ - @spark-web/box@6.0.1
15
+ - @spark-web/stack@5.1.1
16
+ - @spark-web/text@5.3.1
17
+
18
+ ## 5.3.0
19
+
20
+ ### Minor Changes
21
+
22
+ - [#667](https://github.com/brighte-labs/spark-web/pull/667)
23
+ [`80d9c15`](https://github.com/brighte-labs/spark-web/commit/80d9c156a40bbcd2b1a91a2d0403b3c8e9b47b4e)
24
+ Thanks [@Leo704099](https://github.com/Leo704099)! - Support react 17 to 19
25
+
26
+ ### Patch Changes
27
+
28
+ - Updated dependencies
29
+ [[`80d9c15`](https://github.com/brighte-labs/spark-web/commit/80d9c156a40bbcd2b1a91a2d0403b3c8e9b47b4e)]:
30
+ - @spark-web/stack@5.1.0
31
+ - @spark-web/theme@5.13.0
32
+ - @spark-web/utils@5.1.0
33
+ - @spark-web/a11y@5.3.0
34
+ - @spark-web/icon@5.1.0
35
+ - @spark-web/text@5.3.0
36
+ - @spark-web/box@6.0.0
37
+
3
38
  ## 5.2.0
4
39
 
5
40
  ### Minor Changes
package/CLAUDE.md ADDED
@@ -0,0 +1,80 @@
1
+ # @spark-web/field — AI Context
2
+
3
+ ## What this is
4
+
5
+ The form field wrapper. `Field` provides the label, optional description,
6
+ optional validation message, and the accessibility wiring (aria-describedby,
7
+ aria-invalid, id) that connects a label to its input. Every `TextInput`,
8
+ `Select`, and other form input **must** be wrapped in a `Field`.
9
+
10
+ ## What this is NOT
11
+
12
+ - Not the input itself — `Field` only provides the label and context; the input
13
+ (`TextInput`, `Select`, etc.) is the `children`
14
+ - Not a layout component — use `Stack` or `Columns` to arrange multiple `Field`
15
+ components
16
+
17
+ ## Props interface
18
+
19
+ | Prop | Type | Default | Notes |
20
+ | ----------------- | ------------------------------------------ | ----------- | --------------------------------------------------------------------------------------- |
21
+ | `label` | `string` | required | Always required — used for accessibility even if hidden |
22
+ | `labelVisibility` | `'visible' \| 'hidden' \| 'reserve-space'` | `'visible'` | `'hidden'` hides visually but keeps accessible; `'reserve-space'` reserves layout space |
23
+ | `description` | `string \| ReactNode` | — | Hint text rendered below the label |
24
+ | `message` | `string` | — | Validation message; tone controls its appearance |
25
+ | `tone` | `'neutral' \| 'critical' \| 'positive'` | `'neutral'` | `'critical'` marks the input invalid |
26
+ | `secondaryLabel` | `string` | — | Supplementary label text (e.g. "Optional") |
27
+ | `disabled` | `boolean` | `false` | Disables the child input via context |
28
+ | `readOnly` | `boolean` | `false` | Makes the child input read-only via context |
29
+ | `adornment` | `ReactElement` | — | Utility element placed inline with the label (e.g. tooltip) |
30
+ | `data` | `DataAttributeMap` | — | Test/analytics attributes |
31
+
32
+ ## Common patterns
33
+
34
+ ### Standard labeled input
35
+
36
+ ```tsx
37
+ <Field label="Email address">
38
+ <TextInput type="email" placeholder="you@example.com" />
39
+ </Field>
40
+ ```
41
+
42
+ ### Hidden label (filter context)
43
+
44
+ Use `labelVisibility="hidden"` when the placeholder or surrounding context makes
45
+ the label redundant visually, but the label is still required for a11y:
46
+
47
+ ```tsx
48
+ <Field label="Search users" labelVisibility="hidden">
49
+ <TextInput placeholder="Search users">
50
+ <InputAdornment placement="start">
51
+ <SearchIcon size="xsmall" tone="placeholder" />
52
+ </InputAdornment>
53
+ </TextInput>
54
+ </Field>
55
+ ```
56
+
57
+ ### Validation state
58
+
59
+ ```tsx
60
+ <Field label="Password" tone="critical" message="Password is required">
61
+ <TextInput type="password" />
62
+ </Field>
63
+ ```
64
+
65
+ ### Optional field
66
+
67
+ ```tsx
68
+ <Field label="Phone number" secondaryLabel="Optional">
69
+ <TextInput type="tel" />
70
+ </Field>
71
+ ```
72
+
73
+ ## Do NOTs
74
+
75
+ - NEVER use `TextInput` or `Select` without wrapping them in `Field`
76
+ - NEVER omit `label` — it is always required for accessibility, even with
77
+ `labelVisibility="hidden"`
78
+ - NEVER pass `id` to the input directly — `Field` manages the id via context
79
+ - NEVER use `tone="critical"` without also providing `message` — the tone alone
80
+ does not communicate the error to the user
package/dist/declarations/src/context.d.ts CHANGED
@@ -1,15 +1,14 @@
1
- /// <reference types="react" />
2
- export declare type FieldState = {
1
+ export type FieldState = {
3
2
  disabled: boolean;
4
3
  invalid: boolean;
5
4
  readOnly?: boolean;
6
5
  };
7
- export declare type InputPropsDerivedFromField = {
6
+ export type InputPropsDerivedFromField = {
8
7
  'aria-describedby'?: string;
9
8
  'aria-invalid': true | undefined;
10
9
  id: string;
11
10
  };
12
- export declare type FieldContextType = [FieldState, InputPropsDerivedFromField];
11
+ export type FieldContextType = [FieldState, InputPropsDerivedFromField];
13
12
  export declare const FieldContext: import("react").Context<FieldContextType | null>;
14
13
  export declare const FieldContextProvider: import("react").Provider<FieldContextType | null>;
15
14
  export declare const FIELD_CONTEXT_ERROR_MESSAGE = "Input components must be inside a `Field`.";
package/dist/declarations/src/field.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import type { DataAttributeMap } from '@spark-web/utils/internal';
2
2
  import type { ReactElement, ReactNode } from 'react';
3
- export declare type Tone = keyof typeof messageToneMap;
4
- export declare type FieldProps = {
3
+ export type Tone = keyof typeof messageToneMap;
4
+ export type FieldProps = {
5
5
  /** Sets a unique identifier for the component. */
6
6
  id?: string;
7
7
  /** Sets data attributes on the component. */
@@ -48,6 +48,6 @@ declare const messageToneMap: {
48
48
  readonly neutral: "muted";
49
49
  readonly positive: "positive";
50
50
  };
51
- declare type FieldMessageProps = Required<Pick<FieldProps, 'message' | 'id' | 'tone'>>;
51
+ type FieldMessageProps = Required<Pick<FieldProps, 'message' | 'id' | 'tone'>>;
52
52
  export declare const FieldMessage: ({ message, id, tone }: FieldMessageProps) => import("@emotion/react/jsx-runtime").JSX.Element;
53
53
  export {};
package/dist/spark-web-field.cjs.d.ts CHANGED
@@ -1,2 +1,2 @@
1
- export * from "./declarations/src/index";
1
+ export * from "./declarations/src/index.js";
2
2
  //# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3Bhcmstd2ViLWZpZWxkLmNqcy5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi9kZWNsYXJhdGlvbnMvc3JjL2luZGV4LmQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEifQ==
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@spark-web/field",
3
- "version": "5.2.0",
3
+ "version": "5.3.1",
4
4
  "homepage": "https://github.com/brighte-labs/spark-web#readme",
5
5
  "repository": {
6
6
  "type": "git",
@@ -11,26 +11,27 @@
11
11
  "module": "dist/spark-web-field.esm.js",
12
12
  "files": [
13
13
  "CHANGELOG.md",
14
+ "CLAUDE.md",
14
15
  "dist",
15
16
  "README.md"
16
17
  ],
17
18
  "dependencies": {
18
19
  "@babel/runtime": "^7.25.0",
19
20
  "@emotion/react": "^11.14.0",
20
- "@spark-web/a11y": "^5.0.0",
21
- "@spark-web/box": "^5.2.2",
22
- "@spark-web/icon": "^5.0.0",
23
- "@spark-web/stack": "^5.0.2",
24
- "@spark-web/text": "^5.2.3",
25
- "@spark-web/theme": "^5.12.1",
26
- "@spark-web/utils": "^5.0.0"
21
+ "@spark-web/a11y": "^5.3.0",
22
+ "@spark-web/box": "^6.0.1",
23
+ "@spark-web/icon": "^5.1.0",
24
+ "@spark-web/stack": "^5.1.1",
25
+ "@spark-web/text": "^5.3.1",
26
+ "@spark-web/theme": "^5.13.0",
27
+ "@spark-web/utils": "^5.1.0"
27
28
  },
28
29
  "devDependencies": {
29
- "@types/react": "^18.2.0",
30
- "react": "^18.2.0"
30
+ "@types/react": "^19.1.0",
31
+ "react": "^19.1.0"
31
32
  },
32
33
  "peerDependencies": {
33
- "react": ">=17.0.2"
34
+ "react": "^17.0.0 || ^18.0.0 || ^19.0.0"
34
35
  },
35
36
  "engines": {
36
37
  "node": ">=14"